JSON Schema

A JSON Schema (opens new window) is a JSON document describing the structure of another JSON document. A JSON Schema can be used to validate a JSON document. A JSON Schema also serves as documentation.

We use JSON Schemas to describe the structure of an object and what you can do with it. Currently we use v3 but it will be upgraded once the working draft has been submitted to the IETF.

Many of the API classes representing entities such as Article, Customer, etc. have the methods get, set, validate and getSchema. These work together in a way illustrated using the Article class:

For instance, when updating an article using Article.set, the resulting article is validated using its schema and if the schema validation fails, an error is returned and the article is not updated.

To do only validation without actually trying to update the article, use Article.validate.

To do a client-side validation, Article.getSchema can be used to fetch the schema. Then validate the article using a 3rd party JSON-Schema validator for your programming language of choice.

The same pattern is applicable for Articlegroup, Customer, Order and most of the other API classes.

Varying schemas

Note that the instances' schema will vary depending on both context (most notably authorization) and the instance itself. For example, an Article in a shop system will have the property "/subshopVariants", which will not be present in a regular shop. The schema can also vary between individual articles in the same shop. Therefore, don't reuse the same schema e.g. to validate multiple articles.

JSON Pointer

A property is defined by its place in the schema. In messages from the API, a property is referenced using a JSON Pointer, e.g. "/name/sv".

Example

• API Console
• PHP
• JSON
• Response

Order.validate(12345678, {
  "currency": "blablablabla",
  "language": "sv"
})

JSON-Schema extensions

We have added some extra property definitions to the schema.

• enumNames refers to readable option names for enums.
• position is an integer referring to the position that a property has in a internal list. -1 can be used when inserting a new object at the top, i.e. before all the other objects in the list.

Avoid depending on these extensions as they may be removed in a future version.