Syntax for schema configuration files

The file attributes

The initial part of a schema extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

The definitions section

The definitions section lists definitions for one or more schemas. For each schema, the following attributes are specified:

• A schema title and description, which is used for API definition documentation.
• The resource type, which, for Cloud API, is typically set to object.
• A list of properties for the schema.

Every schema property includes:

• The property name (such as activityPattern in the example below)
• The property's title and description, which is used for API definition documentation.
• A "datatype" for the property.
  • For scalar value properties, type is specified. This defines the JSON datatype of the property.
  • For compound value properties (such as typekeys), ref is specified. This defines the URI reference for the property.
• Optional attributes as needed for the business functionality of the property.

"definitions": {
  "Activity": {
    "title": "Activity",
    "description": "An `Activity` is an assignable item...",
    "type": "object",
    "properties": {
      "activityPattern": {
        "title": "Activity pattern",
        "description": "The code of the `ActivityPattern` used...
        "type": "string"
        ...
      },
      "activityType": {
        "title": "Activity type",
        "description": "The type of this activity, such as `general`...",
        "$ref": "#/definitions/TypeKeyReference",
        ...
      },
      ...
    }
  }
}

The file attributes

The initial part of a mapping extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

The mapping section

A mapping file contains a mappers section, which lists one or more API resources and, for each readable property in the resource, the way data is mapped to the property.

For each resource, the following attributes are specified:

• The schemaDefinition that defines the structure of the resource
  • This references a schema declared in a schema.json file.
• The data model entity that serves as the root for mapping information for this resource.
• A list of properties

Every mapper property includes:

• The property name (such as closeDate, description, and mandatory in the example below)
  • A path attribute. This is a Gosu expression that is used to populate the value of the property. Typically, this expression returns a value from the entity defined in the root attribute.
  • Depending on the nature of the property, there may be additional attributes.

"mappers": {
  "Activity": {
    "schemaDefinition": "Activity",
    "root": "entity.Activity",
    "properties": {
      "closeDate": {
        "path": "Activity.CloseDate"
      },
      "description": {
        "path": "Activity.Description"
      },
      "mandatory": {
        "path": "Activity.Mandatory"
      },
      ...
    }
  }
}

Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json file.)
• The root for the resource mapping is entity.Activity.
• For each instance of the resource:
  • The closeDate property is set to the Activity entity's CloseDate field.
  • The description property is set to the Activity entity's Description field.
  • The mandatory property is set to the Activity entity's Mandatory field.

The file attributes

The initial part of an updater extension file contains attributes about the file itself. Do not modify these attributes, as doing so could cause Cloud API to behave in unexpected ways.

The updaters section

An updater file contains an updaters section, which lists one or more API resources and, for each writeable property in the resource, the way data is mapped to the data model.

For each resource, the following attributes are specified:

• The schemaDefinition that defines the structure of the resource
  • This references a schema declared in a schema.json file.
• The data model entity that serves as the root for mapping information for this resource.
• A list of properties

Every updater property includes:

• The property name (such as description and mandatory in the example below)
• A path attribute. This defines, for each resource property, the data model entity property into which the resource property is to be written.
• Depending on the nature of the property, there may be additional attributes.

"updaters": {
  "Activity": {
    "schemaDefinition": "Activity",
    "root": "entity.Activity",
    "properties": {
      "description": {
        "path": "Activity.Description"
      },
      "mandatory": {
        "path": "Activity.Mandatory"
      },
      ...
    }
  }
}

Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json file.)
• The root for the resource mapping is entity.Activity.
• For each instance of the resource:
  • The value of the description property is written to the Activity entity's Description field.
  • The value of the mandatory property is written to the Activity entity's Mandatory field.

Note that there may be properties that appear in the mapping file but not the updater file. This typically occurs with properties that are read-only. For example, the Activity entity has a CloseDate property, which the application sets when the activity is closed. This property appears in the mapping file, as it can be read. But it does not appear it the updater file because it cannot be written to.