jsonService

jsonService is a REST data service which stores JSON data with a specified JSON schema .

Schema files are always named schema.config.json. They apply to all resources on the same directory level and in any subdirectories which don't contain their own schema file.

In the Admin interface, you can see and edit the JSON schema applicable to a directory by clicking on the directory itself, it is not listed as being within the directory. The Admin interface won't let you create items within a directory which doesn't have an applicable schema. The Admin interface builds a form based on the schema you supplied. The form builder can handle most schema features, including conditionals. See the schema-form readme  for more details. The schema is used to validate the form.

Restspace makes use of a couple of non-standard properties which must be set on the top level of the schema:

  • pathPattern: this determines how to determine the name of this JSON resource. If set to 'index' there is only one JSON resource in this directory: the default one. Otherwise it should contain a property macro ${propPath}. This is substituted for the value of the property at 'propPath' (a property path).
  • summaryProperties: this is a list of strings which are the names of all top-level JSON properties which form part of the summary object. A summary object is stored in a list in the summaries.config.json file for the directory. See below for more on this.

When doing a GET request to read a JSON item, the Content-Type header returned will be in the format:

application/schema-instance+json; schema="http://mysite/myjson/mydirectory/schema.config.json"

This gives you a link to the schema applicable to the data you read. The Content-Type for schemas is

application/schema+json

jsonService supports the PATCH method, merging the request body with the existing JSON using the semantics of Lodash _.merge .

jsonService has one special configuration property:

  • uploadBaseUrl: this is used by the Admin site form generator to know to what url to send files which are uploaded into upload fields. The file will be uploaded to
    <uploadBaseUrl>/...<service path of current resource>/...<object property path of current field>/<filename>

Summaries & Querying

jsonService will, if the summaryProperties property is set on the top level of the schema, store summary data on each item with the directory which is kept up to date every time a change is made. Only the top-level properties whose name are given as a list in summaryProperties are saved. The purpose of this is to make queries more efficient. The saving can be substantial where the JSON data is used as content, as properties contain large blocks of text can be excluded.

To retrieve a list of summaries, use a query like this:

GET /json/dataType/dataDirectory/?$filter=prop eq 'abc'&$orderby=index

The slash before the ? query operator is important here. This uses a restricted OData syntax. See the OData docs  for more information. Currently support is minimal and listed below:

  • $top, $skip for paging
  • $orderby with multiple ascending or descending indexes
  • $filter with comparison (using eq, ne, gt, lt, ge, le) of properties (including property paths) and string, date or number literals, with logical conjuctions (and & or).