1. Data exchange format - nuvoleweb/integration GitHub Wiki

Data is exchanged using a pre-defined format providing support for:

• Custom metadata
• Multilingual content
• References between content items

Metadata

Each document must have the following list of metadata properties on its root level.

| Name | Description | | --- | --- | --- | | _id | Document ID, unique per Backend. For example g39g84hb0428bhf0s1389xziv7r83f33 | | type | Document type, it usually matches with the Resource Schema this document refers to. For example article | | default_language | Default document language as ISO639 codes or und for "Undetermined" as defined by ISO639-2. For example en, fr or und. | | languages | List of languages the document is available into, generally expressed in a form of an array. For example in JSON: ['en', 'fr']. | | producer_content_id | Content ID unique to the document producer. For example if the producer is a Drupal site then the triplet entity_type-entity_bundle-entity_id is generally a good candidate, like node-article-1. | | producer | Name uniquely identifying a Producer withing a specific Backend. | | created | Creation date as YYYY-MM-DD HH:MM:SS. For example 2015-02-19 20:35:34 | | updated | Last update date as YYYY-MM-DD HH:MM:SS. For example 2015-02-19 20:35:34 |

Other custom metadata properties can be added but they would need to be handled separately.

Fields

The exchanged data is stored in a section rooted by the fields property, having the actual fields as sub-property. Each field will express its data as a list language codes having an array of strings as values. For example:

Referenced fields

Referenced fields will use the und language code and they will contain a list of other documents' IDs.

Default JSON format

JSON is the preferred notation for the data exchange format, although that can be changed by writing a custom formatter plugin to produce and consume data in any other formats.

Below an example of a valid data exchange document:

{
  "_id": "b849bh0qh0qnciwpvi3tn342kc39c24b",
  "type": "article",
  "default_language": "en",
  "producer_content_id": "producer_id",
  "producer": "producer",
  "created": "2015-02-19 20:35:34",
  "updated": "2015-02-23 10:52:34",
  "languages": [
    "fr",
    "en"
  ],
  "fields": {
    "title": {
      "en": [
        "English title article 1"
      ],
      "fr": [
        "French title article 1"
      ]
    },
    "abstract": {
      "en": [
        "English abstract article 1"
      ],
      "fr": [
        "French abstract article 1"
      ]
    },
    "reference": {
      "und": [
        "73765236mkxc3ib92293r9id9guw84u9"
      ]
    }
  }
}

JSON Schema

Documents must validate against the JSON schema below (for example using http://jsonschemalint.com/ or similar tools):

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "version": "1.0",
  "type": "object",
  "properties": {
    "_id": {
      "type": "string",
      "pattern": "^[0-9A-Za-z-_]*$"
    },
    "type": {
      "type": "string",
      "pattern": "^[0-9A-Za-z-_]*$"
    },
    "producer": {
      "type": "string"
    },
    "producer_content_id": {
      "type": "string"
    },
    "created": {
      "type": "string",
      "pattern": "^([0-9]{2,4})-([0-1][0-9])-([0-3][0-9])(?:( [0-2][0-9]):([0-5][0-9]):([0-5][0-9]))$"
    },
    "updated": {
      "type": "string",
      "pattern": "^([0-9]{2,4})-([0-1][0-9])-([0-3][0-9])(?:( [0-2][0-9]):([0-5][0-9]):([0-5][0-9]))$"
    },
    "default_language": {
      "type": "string",
      "pattern": "^([a-z]{2}|und)$"
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^([a-z]{2}|und)$"
      },
      "additionalProperties": false
    },
    "fields": {
      "type": "object",
      "patternProperties": {
        "^[a-z_]*$": {
          "type": "object",
          "patternProperties": {
            "^([a-z]{2}|und)$": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "_id",
    "fields",
    "type",
    "producer",
    "producer_content_id",
    "created",
    "updated",
    "default_language",
    "languages"
  ]
}