ISO/IEC TS 24751-4:2019

Information technology for learning, education and training — AccessForAll framework for individualized accessibility — Part 4: Registry server API

This document specifies an API in support of ISO/IEC DIS 24751-1. In particular, this document specifies: — a data format (in JSON) for the exchange of registry entries (AfA concept records) between registry servers; — a set of RESTful operations for AfA registry servers to allow for the manipulation of AfA concept registry entries by external clients other than server-internal web interfaces.

Technologies de l'information pour l'apprentissage, l'éducation et la formation — Cadre AccessForAll pour l'accessibilité individualisée — Partie 4: API du serveur de registre

General Information

• Status: Withdrawn
• Publication Date: 04-Jun-2019
• ICS: 03.100.30 - Management of human resources
• ICS: 35.240.90 - IT applications in education
• Technical Committee: ISO/IEC JTC 1/SC 36 - Information technology for learning, education and training
• Drafting Committee: ISO/IEC JTC 1/SC 36/WG 7 - ITLET - Culture, language and individual needs
• Current Stage: 9599 - Withdrawal of International Standard
• Completion Date: 03-Feb-2023

Relations

• Revised: ISO/IEC 24751-4:2023 - Information technology — Individualized adaptability and accessibility in e-learning, education and training — Part 4: "Access for all" framework for individualized accessibility and registry server application programming interface (API)
• Effective Date: 01-Jan-2022

Standards Content (Sample)

TECHNICAL ISO/IEC TS
SPECIFICATION 24751-4
First edition
2019-06
Information technology for learning,
education and training — AccessForAll
framework for individualized
accessibility —
Part 4:
Registry server API
Reference number
ISO/IEC TS 24751-4:2019(E)
©
ISO/IEC 2019

---------------------- Page: 1 ----------------------
ISO/IEC TS 24751-4:2019(E)

COPYRIGHT PROTECTED DOCUMENT
© ISO/IEC 2019
All rights reserved. Unless otherwise specified, or required in the context of its implementation, 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
CP 401 • Ch. de Blandonnet 8
CH-1214 Vernier, Geneva
Phone: [phone]
Fax: [phone]
Email: [e-mail]
Website: www.iso.org
Published in Switzerland
ii © ISO/IEC 2019 – All rights reserved

---------------------- Page: 2 ----------------------
ISO/IEC TS 24751-4:2019(E)

Contents Page
Foreword .iv
Introduction .v
1 Scope . 1
2 Normative references . 1
3 Terms and definitions . 1
4 Symbols and abbreviated terms . 2
5 Conformance . 2
6 REST architecture . 2
6.1 General . 2
6.2 Request and response parameters . 3
6.3 Response codes . 3
6.4 Security considerations . 4
6.5 Authentication . 4
6.6 MIME type . 4
6.7 Other general requirements . 4
7 Registry API (JSON mapping) . 5
7.1 General . 5
7.2 Concept record (JSON format) . 5
7.3 CREATE concept record . 7
7.4 UPDATE concept record . 9
7.5 DELETE concept record .12
7.6 GET concept record .12
7.7 GET list of concept records .13
Bibliography .16
© ISO/IEC 2019 – All rights reserved iii

---------------------- Page: 3 ----------------------
ISO/IEC TS 24751-4:2019(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.
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) or the IEC
list of patent declarations received (see http: //patents .iec .ch).
Any trade name used in this document is information given for the convenience of users and does not
constitute an endorsement.
For an explanation of the voluntary nature of standards, the meaning of ISO specific terms and
expressions related to conformity assessment, as well as information about ISO's adherence to the
World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT) see www .iso
.org/iso/foreword .html.
This document was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 36, Information technology for learning, education and training.
A list of all parts in the ISO/IEC 24751 series can be found on the ISO website.
Any feedback or questions on this document should be directed to the user’s national standards body. A
complete listing of these bodies can be found at www .iso .org/members .html.
iv © ISO/IEC 2019 – All rights reserved

---------------------- Page: 4 ----------------------
ISO/IEC TS 24751-4:2019(E)

Introduction
For individualized accessibility, the needs and preferences of individual users need to be described
in a concise and machine-readable manner. User interfaces and their components can then read such
personal "AfA preference statements" and accommodate them in their adaptations. In addition, other
aspects of the context of use need to be described so that user interfaces and their components can take
the user's tasks, their equipment and their environment into account. Also, user interface resources
need to be described so that “AfA services” can identify the most appropriate resources for a specific
context of use.
For all descriptions, vocabularies are instrumental to allow for a strict semantic and machine-readability.
1)
ISO/IEC DIS 24751-1 introduces an AfA concept registry for “AfA concepts” for the description of AfA
preference statements, other aspects of the context of use and user interface resources. For each AfA
concept, a concept record contains a globally unique identifier and other characteristics of the AfA
concept.
An AfA concept registry needs to be globally accessible through a well-defined API and format rules
need to exist for the exchange of AfA concept records. This document specifies a RESTful API for an
AfA concept registry service (a.k.a. registry server) and a JSON format for AfA concept records to be
exchanged through the AfA concept registry API.
The following use cases are meant to illustrate the benefits of a standardized API and AfA concept
record format. This list of use cases is not meant to restrict further uses of this document in any way.
— A person using an AfA concept registry (e.g., a developer of an assistive technology solution)
registers an AfA concept on a registry server. This can be facilitated by either a web interface of the
registry or by a third-party development application (e.g., an integrated development tool) running
on the person's computer. The third-party development application has some advantages over the
web interface since it allows for a tighter integration of development platform and registry server.
It requires the definition of a concept registry API and of the format an AfA concept record.
— An infrastructure component (e.g., a tool for setting up AfA preference statements or an AfA service)
looks up an AfA concept on a registry server. Thus, the definition of an AfA concept can be presented
to the user or the range of allowed values of an AfA concept can be considered for the identification
of matching AfA resources.
— A syntax checker (e.g., special lint tool) verifies the contents of a new AfA preference statement by
validating against the AfA concept records on a registry server. By this procedure, invalid values for
AfA concepts can be detected. In case of an invalid AfA preference statement, the syntax checker can
notify the user about the error or make automatic corrections.
NOTE 1 A syntax checker could be part of a service managing AfA preference statements, checking
everything incoming AfA preference statement for syntax errors before storing it.
— Two services managing AfA preference statements synchronize their AfA preference statements.
This could be a full synchronization over all contained AfA preference statements, or it could affect
only a part of the statements. To avoid the distribution of invalid content, incoming statements can
be verified against the AfA concept records of an AfA registry server (e.g., to detect invalid values),
and erroneous statements can be skipped or automatically corrected.
— Two AfA registry servers synchronize their entries. This could be a full synchronization over all
contained AfA concept records or it could affect only a part of the entries.
1) 2nd Edition under development. Stage at time of publication: ISO/IEC DIS 24751-1:2018.
© ISO/IEC 2019 – All rights reserved v

---------------------- Page: 5 ----------------------
ISO/IEC TS 24751-4:2019(E)

NOTE 2 While ISO/IEC DIS 24751-1 leaves open whether there is a single registry server or multiple
registry servers, it is possible to run multiple registry servers globally. Some organizations have built, for
security and privacy reasons, self-contained digital infrastructures (such as intranets) with only very few
and well-defined gateways to the external internet. Such organizations would possibly prefer to have their
own registry server running in their infrastructure, and have it synchronize with some global registry
server in a secured way from time to time. Also, organizations that develop adaptive user interfaces or
assistive technology solutions would likely want to have their own registry server for experimentation
purposes.
vi © ISO/IEC 2019 – All rights reserved

---------------------- Page: 6 ----------------------
TECHNICAL SPECIFICATION ISO/IEC TS 24751-4:2019(E)
Information technology for learning, education and
training — AccessForAll framework for individualized
accessibility —
Part 4:
Registry server API
1 Scope
This document specifies an API in support of ISO/IEC DIS 24751-1. In particular, this document specifies:
— a data format (in JSON) for the exchange of registry entries (AfA concept records) between registry
servers;
— a set of RESTful operations for AfA registry servers to allow for the manipulation of AfA concept
registry entries by external clients other than server-internal web interfaces.
2 Normative references
The following documents are referred to in the text in such a way that some or all of their content
constitutes requirements of this document. For dated references, only the edition cited applies. For
undated references, the latest edition of the referenced document (including any amendments) applies.
ISO/IEC 10646, Information technology — Universal Coded Character Set (UCS)
2)
ISO/IEC/DIS 24751-1, Information technology — Information technology for learning, education and
training — AccessForAll Framework For Individualized Accessibility — Part 1: Framework and Registry
IETF RFC 2046, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, November 1996,
ht t p s: //t o ol s . ie t f . or g / ht m l/r f c 20 4 6
IETF RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, June 2014, https: //tools
. ie t f . or g /ht m l/r f c7231
IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005, https: //tools .ietf
.org/html/rfc3986
IETF RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format, March 2014. https:
//t o ol s . ie t f . or g /ht m l/r f c7159
IETF BCP 47, Tags for Identifying Languages, September 2009. ht t p s: //t o ol s . ie t f . or g / ht m l/ b c p 47
3 Terms and definitions
For the purposes of this document, the terms and definitions of ISO/IEC DIS 24751-1, and the following
terms and definitions apply.
ISO and IEC maintain terminological databases for use in standardization at the following addresses:
— ISO Online browsing platform: available at https: //www .iso .org/obp/
2) 2nd Edition under development. Stage at time of publication: ISO/IEC DIS 24751-1:2018.
© ISO/IEC 2019 – All rights reserved 1

---------------------- Page: 7 ----------------------
ISO/IEC TS 24751-4:2019(E)

— IEC Electropedia: available at http: //www .electropedia .org/
3.1
AfA concept record
concept record
record for an AfA concept in the AfA concept registry
3.2
registry server
service running an AfA concept registry
4 Symbols and abbreviated terms
AfA AccessForAll
API application programming interface
HTTP hypertext transfer protocol (IETF RFC 7230, IETF RFC 2731)
HTTPS HTTP secure (IETF RFC 7230, IETF RFC 2731)
JSON JavaScript object notation (IETF RFC 7159)
MIME multi-purpose internet mail extensions (IETF RFC 2046)
URI uniform resource indicator (IETF RFC 3986)
REST representational state transfer (Fielding, 2000)
5 Conformance
A conforming registry server shall meet the following requirements:
— REST architecture, as specified in Clause 5;
— The JSON mapping for the registry API, as specified in Clause 7.
A conforming registry server may support additional format mappings for the registry API.
NOTE The requirements and recommendations in this document apply to a registry server’s API and data
formats for parameters in the API. Nothing in this document is meant to constrain the design, data structure and
implementation of the internal parts of a registry server, including its database of AfA concepts.
6 REST architecture
6.1 General
The interface specified in this document is based on the representational state transfer (REST)
architecture (Fielding, 2000; Richardson et al., 2015). Hereby, an established relationship between a
resource service and a client is provided that is easy to implement, test and maintain on both sides.
According to REST, HTTP methods (see IETF RFC 7231) are used to manipulate REST resources which
are located on a resource service:
— POST creates a new resource with a new URI.
— GET retrieves a resource.
— PUT modifies a resource.
2 © ISO/IEC 2019 – All rights reserved

---------------------- Page: 8 ----------------------
ISO/IEC TS 24751-4:2019(E)

— DELETE deletes a resource.
NOTE These methods are called "HTTP methods" according to IETF RFC 7231 but are applicable for HTTPS
as well. In fact, the use of HTTPS offers a more secure protocol for service implementations (see 6.4).
Each operation has one or multiple request parameters, and one or multiple response parameters, as
specified in 6.2 to 6.7.
6.2 Request and response parameters
The request and response parameters for an operation in this subclause are made up of information
items, each with a specific type. Complex types are Object and Array, primitive types are String, Number,
Boolean, URI (as specified in IETF RFC 3986) and the null value (as specified in IETF RFC 7159).
Each request and response parameter, as used for the operations in this subclause, shall have one of
four different categories:
1. URI path. The parameter is submitted as URI path in a request (as specified in IETF RFC 3986).
EXAMPLE 1 In the operation "PUT /api/record/C12345", the parameter conceptId (value "C12345") is
contained in the path of the URI.
2. URI query parameter. The parameter is submitted as one of the query parameters of the URI (as
specified in IETF RFC 3986).
EXAMPLE 2 In the operation "GET /api/records?type=PreferenceStatement&offset=1&limit=1", the
parameters type (value "PreferenceStatement"), offset (value 1) and limit (value 1) are URI query parameters.
3. HTTP header field. The parameter is submitted as content of an HTTP header field (as specified in
IETF RFC 7231).
EXAMPLE 3 In the following HTTP response header, the parameter record (value "https: //example
.com/api/record/R12345") is submitted as content of the field "Location".
HTTP/1.1 200 OK
Location: https://example.com/api/record/R12345

4. Message body. The parameter is submitted as content of the request/response body, whereby the
body's MIME type is specified through the Content-Type HTTP header field (as specified in IETF
RFC 7231).
EXAMPLE 4 In the following HTTP response body (JSON format), the parameter totalRows (value 1) is
submitted as the field "totalRows" in the unnamed response object.
{
  "ok": true,
  "totalRows": 1
}

In addition to the request and response parameters specified in this subclause, other (proprietary)
request and response parameters may be added to any operation, as long as they do not interfere with
the parameters as specified in this document. Also, additional (proprietary) information may be added
to the parameters specified in this document, as long as they do not interfere with the parameter's
content as specified in this document. If a registry server or client does not know the meaning of such
proprietary information, it shall ignore it.
6.3 Response codes
Format and semantics of HTTP response codes shall adhere to IETF RFC 7231.
NOTE 1 Clause 7 lists only the most important HTTP codes for every operation. Nevertheless, a registry server
can make use of the full range of HTTP response codes as listed in IETF RFC 7231.
© ISO/IEC 2019 – All rights reserved 3

---------------------- Page: 9 ----------------------
ISO/IEC TS 24751-4:2019(E)

In case of an error response code, the registry server shall return a textual description of the error as
response body (see parameter error message in the response bodies in Clause 7).
NOTE 2 Textual descriptions of error messages are important for debugging. They include all relevant
information for developers sending requests to the registry server.
6.4 Security considerations
A registry server should take measures for a level of security that is appropriate for the specific
sensitivity of the data. The employed security mechanisms should be based on state-of-the-art
technologies.
A registry service should provide an HTTPS-based interface (as specified in IETF RFC 7230) for all
operations. For sensitive resources and operations, no HTTP-based interface should be provided.
A client should use HTTPS for communication with a resource service, if available.
6.5 Authentication
A registry server may apply access restrictions to its operations, based on client privileges.
EXAMPLE A service can store ownership information for every REST resource. For example, only owners
(creators) of a REST resource are allowed to modify and delete it.
If a registry server requires authentication, basic authentication (as specified in IETF RFC 2617) or an
authentication mechanism with an equal or higher security level should be supported.
6.6 MIME type
For all operations in Clause 7, the following requirements shall be met:
— A service shall support request bodies in the JSON format. The format (MIME type, see IETF
RFC 2046) of the request body is indicated by the Content-Type field value in the HTTP request
header (as specified in IETF RFC 7231).
— A service shall indicate its response format (MIME type, as specified in IETF RFC 2046) by the
Content-Type field value in the HTTP response header (as specified in IETF RFC 7231).
— A service shall respect a client's preferred response body format (MIME type, as specified in IETF
RFC 2046), as specified by the Accept field value in the HTTP request header (as specified in IETF
RFC 7231). At a minimum, a service shall support the JSON mapping, as specified in Clause 7.
A service may support additional formats for requests and responses. In this case, the additional
formats shall be specified by different MIME types (not listed in this document).
6.7 Other general requirements
For all operations in Clause 7, the following requirements shall be met:
— If used inside a URI for a GET request, reserved characters (as specified in RFC 3986:2005, section
2.2) shall be percent-encoded (as specified in IETF RFC 3986:2005, section 2.1).
— The encoding of request and response shall be UTF-8 (as specified in ISO/IEC 10646).
— The header fields of request and response shall comply with IETF RFC 7231.
4 © ISO/IEC 2019 – All rights reserved

---------------------- Page: 10 ----------------------
ISO/IEC TS 24751-4:2019(E)

7 Registry API (JSON mapping)
7.1 General
For JSON-formatted requests and responses of a registry server, the requirements in this clause
shall be met.
The message body (if applicable) and response body (if applicable) shall comply to JSON (as specified in
IETF RFC 7159), except for error responses which shall be plain text.
The MIME type (as specified in IETF RFC 2046) for the JSON format shall be "application/json".
The null value shall be mapped to the JSON null value (as specified in IETF RFC 7159).
The root object of any request body shall be an unnamed object (hereafter referred to as the request
object).
The root object of any response body shall be an unnamed object (hereafter referred to as the response
object).
The MIME type (as specified in IETF RFC 2046) for an error response message (in plain text) shall be
"text/plain".
Where types are specified for parameters, these shall refer to IETF RFC 7159.
For any request or response body defined in this clause, proprietary information may be added as
additional parameters, or extra fields of an object, even within a nested object, as long as the additional
parameters and fields do not interfere with the information items specified in this clause.
7.2 Concept record (JSON format)
For the JSON representation of a concept record object, when used as a parameter in the registry server’s
API, the following shall apply:
— A concept record object shall be a JSON object.
— Concept record shall have a conceptId member (String without reserved characters for URIs, see
IETF RFC 3986), carrying a locally (i.e. within a registry server) unique identifier for the concept.
conceptId shall be immutable, i.e. it cannot be modified in an update operation (see 7.4).
NOTE 1 The concatenation of the registry server domain, the path for getting a concept record (see 7.6)
and the conceptId yields a globally unique identifier (URI, cf. IETF RFC 3986) for a concept.
EXAMPLE 1 A concept with conceptId “common_fontSize”, stored on a registry server with (sub-)
domain name “terms.gpii.eu”, would have the globally unique URI “https: //terms .gpii .eu/api/record/common
_fontSize” (assuming that the HTTPS protocol is used for accessing the registry server).
— Concept record shall have a type member (String), carrying either one of the following values:
“PreferenceStatement”, “ContextDescription”, “ResourceDescription”. type shall be immutable, i.e.,
it cannot be modified in an update operation (see 7.4).
— Concept record shall have a subtype member (String), carrying either one of the following values:
"term", "transform". subtype shall be immutable, i.e., it cannot be modified in an update operation
(see 7.4).
— Concept record may have an origin member (String), carrying either one of the following values:
"common", "application-specific", or any other value. origin shall be immutable, i.e., it cannot be
modified in an update operation (see 7.4).
— Concept record shall have a definition member (Array). The array shall have one or more unnamed
objects, each with two members: language and value. The language member shall identify a
language (as specified in IETF BCP 47) which may be null. The value member shall bear a textual
© ISO/IEC 2019 – All rights reserved 5

---------------------- Page: 11 ----------------------
ISO/IEC TS 24751-4:2019(E)

definition (String) of the concept in the pertinent language. definition may contain multiple
objects referring to the same language.
— Concept record shall have a termLabel member (Array). The array shall have one or more unnamed
objects, each with two members: language and value. The language member shall identify a
language (as specified in IETF BCP 47) which may be null. The value member shall bear a linguistic
expression (String) for the concept in the pertinent language. termLabel may contain multiple
objects referring to the same language.
— Concept record shall have a datatype member (Object), carrying either one of the following values:
"Boolean", "Number", "String". datatype shall be immutable, i.e., it cannot be modified in an update
operation (see 7.4).
— Concept record shall have an owner member, carrying the contact information of the owner(s) of
the concept, to facilitate addressing any issues with the record. The type of the owner member is
implementation specific.
NOTE 2 Initially, the submitter of a record is the owner. The submitter can extend the ownership to other
parties, or pass it on to other parties, in which case the owner member is updated.
— Concept record may have a valueSpace member (Object), carrying a formal data type definition
such as the JSON Schema format (as specified in JSON Schema, JSON Schema Validation, JSON Hyper-
Schema). valueSpace shall be immutable, i.e., it cannot be modified in an update operation (see 7.4).
— Concept record may have a transformationOf member (Array). If present, the transformationOf
array shall consist of one or more Strings, each representing a globally unique identifier (conceptId)
of a concept record.
— Concept record may have a refines member (Array), carrying the identifiers of other concepts that
concept refines. If present, the refines array shall consist of one or more Strings, each representing
a globally unique identifier (conceptId) of a concept.
— Concept record may have a domains member (Array). The array shall have one or more unnamed
objects, each with two members: language and value. The language member shall identify a
language (as specified in IETF BCP 47) which may be null. The value member shall carry a textual
description of the domain / application area (String) on the concept in the pertinent language.
domains may contain multiple objects referring to the same language.
— Concept record may have a notes member (Array). The array shall have one or more unnamed
objects, each with two members: language and value. The language member shall identify a
language (as specified in IETF BCP 47) which
...