JSON

JSON Schema

We provide advanced JSON interfaces that are easier to use and understand. Our JSON Schema and OpenAPI documents are:

Unnabreviated

Messages are easier to read with element names that are not abbreviated.

Documented

Documentation is included from the model for elements and components,
making it easier for users and developers to understand.

Compatible

Messages can now be validated with schema for a different type, enabling compatibility between functions, flavours and versions.

Convertible

We support three styles of JSON:

• mixed type = scalar types are string, number or boolean;
  properties are scalar if single valued, or arrays if multi-valued.
• string arrays = scalar types are always string;
  properties always arrays of items.
• WAPI+ (see below)

String arrays have the advantage of simple schema-less conversion to and from XML. Further, if the occurrence of a property changes between versions, queries retain their structure enabling compatibility.
The tradeoff is that even single items are in an array.

Typed scalars require schema specific conversion to/from string arrays XML. To decide what your want, consider what’s most important to you, native format or round trip convertibility ?

WAPI+

WAPI+ is as per ISO/TS 23029:2020 Technical Specification for Web Service Based Application Programming Interfaces in Financial Services (WAPI),
with the following specified improvements:

• Add generation of the Message Definition’s type,
  containing Message Building Block properties as per Message Element.
• Message Element generated as per example (“$ref”:type),
  rather then text (“properties”:{ “$ref”:type }).
• Use the currencyIdentifierSet’s name (as they don’t have types),
  for the name and type of the currency property in an Amount.
• Code literal inferred from corresponding conceptual CodeSet code.
• Wrap the RegEx patterns with head (^) and tail ($).
• Generate unspecified types as string.
  ( UserDefined, SchemaType, and other date time types. )

This table compares the applicaiton of JSON styles to ISO20022.

JSON±LD

Our JSON schema now supports JSON-LD, an RDF serialisation format,
by permitting the use of @type, @context, and decimal value objects.
This enables JSON with or without JSON-LD enhancements.

JSON-LD, as with any RDF format, can also be validated with SHACL.
Validation reporting has been improved to provide more specific information, making it easier and quicker to find invalid data.

OpenAPI document

RESTful API skeletons

These provide a basic RESTful API skeleton definition,
permitting only the creation and reading of a resources in a collection.

	/resource-type	/resource-type/{id}
GET	200 OK	200 OK
POST	201 Created	403 Forbidden
PUT	403 Forbidden	200 OK
PATCH	403 Forbidden	403 Forbidden
DELETE	403 Forbidden	403 Forbidden

Would you like RESTful API skeletons that permit a wider range of actions, and response codes. If so, which ones would you like ?

What else would you like to see in OpenAPI documents ?

Please send feedback to api@iso20022.plus.