ISO/IEC 24800-3:2010/Amd 1:2015

INTERNATIONAL ISO/IEC
STANDARD 24800-3
First edition
2010-05-01
AMENDMENT 1
Information technology — JPSearch —
Part 3:
Query format
AMENDMENT 1: JPSearch API
Technologies de l’information — JPSearch —
Partie 3: Format d’interrogation
AMENDEMENT 1: API JPSearch
PROOF/ÉPREUVE
Reference number
ISO/IEC 24800-3:2010/Amd.1:2015(E)
©
ISO/IEC 2015
ISO/IEC 24800-3:2010/Amd.1:2015(E)

© ISO/IEC 2015, Published in Switzerland
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form
or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior
written permission. Permission can be requested from either ISO at the address below or ISO’s member body in the country of
the requester.
ISO copyright office
Ch. de Blandonnet 8 • CP 401
CH-1214 Vernier, Geneva, Switzerland
Tel. +41 22 749 01 11
Fax +41 22 749 09 47
copyright@iso.org
www.iso.org
ii © ISO/IEC 2015 – All rights reserved

ISO/IEC 24800-3:2010/Amd.1:2015(E)

Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are
members of ISO or IEC participate in the development of International Standards through technical
committees established by the respective organization to deal with particular fields of technical
activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international
organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the
work. In the field of information technology, ISO and IEC have established a joint technical committee,
ISO/IEC JTC 1.
The procedures used to develop this document and those intended for its further maintenance are
described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for
the different types of document should be noted. This document was drafted in accordance with the
editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives).
Attention is drawn to the possibility that some of the elements of this document may be the subject
of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent
rights. Details of any patent rights identified during the development of the document will be in the
Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents).
Any trade name used in this document is information given for the convenience of users and does not
constitute an endorsement.
For an explanation on the meaning of ISO specific terms and expressions related to conformity
assessment, as well as information about ISO’s adherence to the WTO principles in the Technical
Barriers to Trade (TBT) see the following URL: Foreword - Supplementary information
The committee responsible for this document is ISO/IEC JTC 1, Information technology, Subcommittee
SC 29, Coding of audio, picture, multimedia and hypermedia information.
© ISO/IEC 2015 – All rights reserved PROOF/ÉPREUVE iii

ISO/IEC 24800-3:2010/Amd.1:2015(E)
Information technology — JPSearch —
Part 3:
Query format
AMENDMENT 1: JPSearch API
Add the following paragraph at the end of Clause 1.
In addition, this part of ISO/IEC 24800 specifies the JPSearch API, a Restful State (REST) Application
Programming Interface, complementary to the JPSearch Query Format (JPQF). It is primarily intended
to be used for web services. Compared to JPQF, it does not only specify the query syntax, but also the
protocols used for sending and retrieving queries. It reduces the complexity of expressing image search
queries by providing a simplified syntax to express common queries in the form of URIs. Furthermore,
the API allows embedding JPQF queries to express more advanced queries or to use the API solely as a
communication protocol for sending and retrieving queries between client and repository. In addition
to text based search queries, the API provides functionality to support visual search applications, such
as content-based image retrieval systems.
Change the title of Clause 5 “Disabled datatypes” to “JPQF Disabled datatypes”.
Change the title of Clause 6 “Disabled Query Types” to “JPQF Disabled Query Types”.
Move Clause 7 “Conformance” to the end of the document and update numbering.
Add the following clauses to the end of the document (before Conformance).
7 Basic concepts of the JPSearch API
The API builds upon the HyperText Transfer Protocol (HTTP) for client-server communication. More
specifically, in the context of a JPSearch-environment, the communication between a JPSearch-client
and a JPSearch-server is specified. A JPSearch-client is any application that can formulate JPSearch-
requests and handle JPSearch-responses. A JPSearch-server is an image repository that answers to
JPSearch-requests and responds compliant with this part of ISO/IEC 24800.
Requests are largely expressed using the Uniform Resource Identifier (URI) syntax. This part of
ISO/IEC 24800 follows the RFC 3986 syntax, as shown below:
URI = scheme “://” authority “/” path [ “?” query ] [ “#” fragment ]

More specifically, this part of ISO/IEC 24800 focuses solely on the “query” part of the former definition.
The query part is a sequence of key value pairs separated with an “&” character. The keys are referred
to as arguments or query options. For example, the following query has three query options arg1,
arg2 and arg3:
?arg1=value1&arg2=value2&arg3=value3

Please note that the URIs should adopt proper URL encoding according to the RFC 3986 specification.
Examples provided in this part of ISO/IEC 24800 are not encoded for the sake of readability.
Query options specified in this part of ISO/IEC 24800 are referred to as “system query options”. These
query options can have the following types:
— signed or unsigned integer;
— real numbers;
ISO/IEC 24800-3:2010/Amd.1:2015(E)

— intervals: [from-to], for example, [0-10] denotes any integer number between 0 and 10, [0.-10.]
denotes any real number between 0 and 10;
— boolean: 0 = false and 1 = true;
— string: strings should be URL encoded. Strings can be restricted to a specific syntax, e.g. a pair is a
string of two values separated with a comma: “x,y”;
— enum: discrete list of valid values, where the options are separated with a “|”. For example:
value1|value2|…;
— time: formatted string according to ISO 8601 representation;
— geolocation: formatted string containing two comma separated real numbers representing latitude
and longitude as decimal degrees with negative numbers for south and west.
A JPSearch repository is completely free to specify the remaining part of the URI, i.e. the scheme,
authority, path and fragments. Furthermore, additional query options can be specified, as long as they
do not infer with the system query options. By default, JPSearch system query options do not have a
prefix. However, in order to avoid collisions with custom query options, a prefix can be specified in the
capability description.
The capability description is a resource served by any JPSearch-server. It specifies the capabilities of
the repository as well as its custom properties and settings. Any system query option can be enabled
or disabled in the capability description. In addition, default values can be overwritten. It is the first
resource requested in an initial interaction between a client and a repository. It informs the client about
what queries can be send and how they should be formatted for the respective repository.
A JPSearch-client requests resources from a JPSearch-server. A JPSearch-server serves the following
resources:
— images: binary image data;
— metadata of images (JPSearch Core metadata or JSON);
— image descriptions (JPOnto);
— collections of images: a set of images (JSON);
— resource identifiers or a collection of resource identifiers: in case the input itself is image data, the
repository may return references to related resources of any kind;
— a JPQF output query (XML);
— a capability description: a description of the capabilities and properties of the respective
repository (JSON).
All these resources are discussed in more detail further in this part of ISO/IEC 24800.
8 JPSearch API: requesting resources
8.1 Image resources
The most essential resource type of an image repository is an individual image. The return type is a
JPEG or JPEG 2000 image file. The original image can be requested by its resource identifier, without
specifying any system query options. Various versions of the original image can be requested by
2 PROOF/ÉPREUVE © ISO 2015 – All rights reserved

ISO/IEC 24800-3:2010/Amd.1:2015(E)

specifying system query options. The following table gives an overview of system query options specific
to image resources.
Argument Description Values Default
crop
Crops the image to a given none|w:h where w:h none
aspect ratio. The image is specifies the aspect
cropped equally to the top and ratio with w = width
bottom or to the left and right. and h = height
This option is ignored if a
region of interest is specified.
discardmd
Specifies whether the Boolean 0
embedded metadata should
be included or discarded.
maxw
Specifies the maximum width Unsigned integer The width of the
of the returned image. requested images.
maxh
Specifies the maximum height Unsigned integer The height of the
of the returned image. requested image.
minw
Specifies the minimum width Unsigned integer The width of the
of the returned image. requested images.
minh
Specifies the minimum height Unsigned integer The height of the
of the returned image. requested image.
quality
Specifies the quality of the Percentage, [1-100] Original of the
returned image image as a requested image,
value between 1 and 100 no recompression
where 1 is the lowest quality
and 100 is the highest quality.
roff
Region offset. Used in left,top 0,0
combination with rsize to
where top and left
request a rectangle region of
are unsigned integers
interest.
specifying the offset in
pixels from the top and
the left respectively
rsize
Region size. Used in width,height The width and height
combination with roff to of the requested image.
where width and height
request a rectangle region of
are unsigned integers
interest.
specifying the width
and the height of the
requested region
scale
Scale of the returned image Percentage, [0.-100.] 100
with respect to the original
image.
thumb
Specifies whether the image Boolean 0
should be returned as a
thumbnail. When a thumbnail
is requested, maxw, maxh,
minw, minh are set to 256,
metadata to discard, crop to
1:1 (square) and quality to 50.
These values are overwritten
when any of these arguments
is specified.
8.2 Image metadata
Some applications need to present metadata of an image without presenting the image itself. Therefore,
metadata can be requested separately from the image by specifying an image URI in combination with the
metadata system query option. Metadata fields can be selected of the JPSearch Core Metadata schema,
ISO/IEC 24800-3:2010/Amd.1:2015(E)

as defined in ISO/IEC 24800-2:2011. Alternatively, additional requestable fields can be defined in the
capability description. When the GPSPositioning is requested, it is returned in the geolocation format
specified in this document. The value of the metadata argument is a comma-separated list of the requested
metadata fields represented by their name or XPath expression. For example, the following request:
http://www.repository.org/image.jpg?metadata=Title,Creators,GPSPositioning/@
latitute,GPSPositioning, RightsDescription/Description

will return the following fields:
— Title: content of the title field;
— Creators: the GivenName and FamilyName of the creators, space separated;
— GPSPositioning/@latitude: latitude attribute value of the GPS localization;
— GPSPositioning: complete GPS positioning;
— RightsDescription/Description: content of the Description field of the RightsDescription element.
The return format is a JSON file that contains the “metadata” field at root level. The metadata element
contains an object with all the requested fields and their values. For example:
{
"metadata": {
"Title": "Title of the image",
"Creators": "John Smith",
"GPSPositioning/@latitude": "50.85",
"GPSPositioning": "50.85,4.35",
"RightsDescription/Description": "Rights description"
Alternatively, when the value is set to all, the complete JPCore metadata is returned. In this case, the
return format is XML, i.e. JPCore metadata is returned according to ISO/IEC 24800-2.
Finally, when it is set to description, a JPOnto description of the image is returned. In this case, the
return format is compliant to the ISO/IEC 24800-2:2011/Amd 1 JPOnto specification.
8.3 Image collections
8.3.1 General
A collection is a set of images identified with a URI. In general, a collection is a subset of all images
served by the repository. The repository is not limited in how it manages its own collections. Typically,
the path part of the URI can be used to identify repositories. For example, an image hosting service may
provide a collection for every user. The collection of a specific user can be identified as follows.
http://www.repository.org/username

If users can organize their pictures in sets, a set might be identified as follows.
http://www.repository.org/username/setname

Alternatively, a repository can opt to identify collections using query options, as long as these do not
collide with the system query options. For example,
http://www.repository.org?user=username

The return type of a collection is a JSON (application/json) file listing the resources of the images in
the collection. Additional system query options can be specified, for example, to filter the results in the
return set. The collection to which these options apply (i.e. the base URI) is referred to as the “context”
of the request.
4 PROOF/ÉPREUVE © ISO 2015 – All rights reserved

ISO/IEC 24800-3:2010/Amd.1:2015(E)

8.3.2 Collection system query options
The following table gives an overview of system query options specific to image collection resources.
Argument Description Values Default
imgmeta
Specifies which metadata of the images none|field1,field2,flield3 none
should be included.
top
Specifies the number of items included Unsigned integer 100
in the response.
skip
Specifies the index of the first returned Unsigned integer 0
item in the response (starting at 0).
orderby
Specifies by what metadata field the relevance|field relevance
returned results should be ordered.
orderdirec-
Specifies whether the returned res
...