gdbots / schemas

Schemas for common gdbots services.

Gdbots Schemas

Schemas for common gdbots services. Browse the json schemas.

Installation

• Git clone the project to your computer:

$ git clone [email protected]:gdbots/schemas.git

• Open terminal and cd to the root directory of this project (where you git cloned it to).
• Run nvm use
• Run npm install
• Run composer install
• Work indefinitely ಠ_ಠ.

Writing Code

Using your IDE you can make changes to XML configs.

You will then need to compile the new configs to JS/PHP.

• Run composer pbjc

schemas's Issues

BUG :: _schema property has an id field

The _schema property has an id field which should be the default value.

    "_schema": {
      "type": "string",
      "pattern": "^pbj:([a-z0-9-]+):([a-z0-9\\.-]+):([a-z0-9-]+)?:([a-z0-9-]+):([0-9]+-[0-9]+-[0-9]+)$",
      "id": "pbj:gdbots:geo::address:1-0-0"
    },

id is not valid here, that's just the default value.

BUG :: Ensure use statements of mixins are scoped/unique

It was possible for a name collision to occur when the mixin used had the same name as another or the concrete message. bring in the latest pbjc and recompiled to resolve this issue. only affected two schemas.

BUG :: json-schema constraints don't allow for variations in message types

When a field of type "message" is used it creates an inline reference which points to an exact version of the message schema. This makes validation problematic as the message isn't likely to always be the same version.

    "ctx_cloud": {
      "type": "object",
      "description": "The \"ctx_cloud\" is set by the server receiving the command and is generally only used internally for tracking and performance monitoring.",
      "anyOf": [
        {
          "$ref": "#/definitions/cloud"
        }
      ],
      "pbj": {
        "type": "message",
        "rule": "single"
      }
    },

inline definitions:

  "definitions": {
    "app": {
      "$ref": "https://schemas.gdbots.io/gdbots/contexts/app/1-0-0.json"
    },
    "cloud": {
      "$ref": "https://schemas.gdbots.io/gdbots/contexts/cloud/1-0-0.json"
    }
  },

In order to make this still validate the field properly and allow for multiple version the definition itself should be an anyOf that allows for any version of the message type.

Using the curie you can get a reference for all versions of the message and generate that array. Php solves this with an interface (one without the version)... json schema has no way to describe "so long as it's a blah, accept it, regardless of version)".

BUG :: GeoPoint json-schema is invalid.

The geo point conversion produces an invalid constraint...
The geo json must allow for ranges for lat and long.

    "geo_point": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "pattern": "^Point$"
        },
        "coordinates": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "minItems": 2,
          "maxItems": 2
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "pbj": {
        "type": "geo-point",
        "rule": "single"
      }
    },

BUG :: MessageRef -> json-schema is invalid

The code generation for a message ref produces an invalid object.

• Make sure ID pattern matches what message ref allows.
• Type is not a valid property. It should be tag and tag allows for:

            case Format::SLUG:
                Assertion::regex($value, '/^([\w\/-]|[\w-][\w\/-]*[\w-])$/', null, $field->getName());
                break;

• The required fields are not from message-ref. looks like a mixture of geo point and message ref. curie and id are required, tag is optional.

    "message_ref": {
      "type": "object",
      "properties": {
        "curie": {
          "type": "string",
          "pattern": "^([a-z0-9-]+):([a-z0-9\\.-]+):([a-z0-9-]+)?:([a-z0-9-]+)$"
        },
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9:_-]+$"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "pbj": {
        "type": "message-ref",
        "rule": "single"
      }
    },

php reference on that object:

/**
 * Represents a reference to a message.  Typically used to link messages
 * together via a correlator or "links".  Format for a reference:
 * vendor:package:category:message:id#tag (tag is optional)
 */
final class MessageRef implements FromArray, ToArray, \JsonSerializable
{
    /** @var SchemaCurie */
    private $curie;

    /**
     * Any string matching pattern /^[\w\/\.:-]+$/
     * @var string
     */
    private $id;

BUG :: json-schema not rebuilding

composer pbjc runs without error but the json-schema files are not generated into ./gh-pages/

Add schemas for collector aka form service

We need schemas for custom forms which can be used for data collection (like google forms, formstack).

BUG :: json-schema built-in formats not always used

Anywhere there's a possibility to use a built-in format it should populate the format property.
http://spacetelescope.github.io/understanding-json-schema/reference/string.html#built-in-formats

Example where it doesn't:

    "ctx_ip": {
      "type": "string",
      "minLength": 0,
      "maxLength": 255,
      "pbj": {
        "type": "string",
        "rule": "single",
        "format": "ipv4",
        "overridable": true
      }
    },

There are also our custom formats that are not enforced by a pattern...

    "provider": {
      "type": "string",
      "minLength": 0,
      "maxLength": 20,
      "pbj": {
        "type": "string",
        "rule": "single",
        "format": "slug"
      }
    },

Using format of slug on a pbj must result in a pattern on the item with the slug regex pattern, which is in StringType in pbj. see StringType and Format class in pbj lib, ref aws3 branch

BUG :: json schema generation for patterns is invalid

The pattern is rendering with escaped slashes...

"pattern": "^[\\w\\s\\(\\)\\[\\]\\{\\}\\/\\.:;-]+$",

Add fields to assets and galleries

Add credit_url, cta_text, cta_url and display_title to asset mixin.

Add credit_url to gallery

Put fields in sequence they are added to message (json-schema)

Right now the json-schema generation puts the fields for the concrete message first and then appends the mixins' fields. In php, the mixins are processed first (as that's the only way to handle field overrides). It would be great if both formats matched. The json-schema would render fields in exactly the same sequence as they were added.

For example:

{
  "$schema": "http://json-schema.org/schema#",
  "id": "https://schemas.gdbots.io/gdbots/pbjx/request/request-failed-response/1-0-0.json",
  "type": "object",
  "properties": {
    "_schema": {
      "type": "string",
      "pattern": "^pbj:([a-z0-9-]+):([a-z0-9\\.-]+):([a-z0-9-]+)?:([a-z0-9-]+):([0-9]+-[0-9]+-[0-9]+)$",
      "id": "pbj:gdbots:pbjx:request:request-failed-response:1-0-0"
    },
    "request": {
      "type": "object",
      "anyOf": [
        {
          "$ref": "#/definitions/request"
        }
      ],
      "pbj": {
        "type": "message",
        "rule": "single"
      }
    },
    "error_code": {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535,
      "pbj": {
        "type": "small-int",
        "rule": "single"
      }
    },
    "error_name": {
      "type": "string",
      "pattern": "^[\\w\\/\\.:-]+$",
      "pbj": {
        "type": "string",
        "rule": "single"
      }
    },
    "error_message": {
      "type": "string",
      "minLength": 0,
      "maxLength": 65535,
      "pbj": {
        "type": "text",
        "rule": "single"
      }
    },
    "response_id": {
      "type": "string",
      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$",
      "pbj": {
        "type": "uuid",
        "rule": "single"
      }
    },
    "created_at": {
      "type": "string",
      "pattern": "^[1-9]{1}[0-9]{12,15}$",
      "pbj": {
        "type": "microtime",
        "rule": "single"
      }
    },
    "ctx_request_ref": {
      "type": "object",
      "properties": {
        "curie": {
          "type": "string",
          "pattern": "^([a-z0-9-]+):([a-z0-9\\.-]+):([a-z0-9-]+)?:([a-z0-9-]+)$"
        },
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9:_-]+$"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "pbj": {
        "type": "message-ref",
        "rule": "single"
      }
    },
    "ctx_correlator_ref": {
      "type": "object",
      "properties": {
        "curie": {
          "type": "string",
          "pattern": "^([a-z0-9-]+):([a-z0-9\\.-]+):([a-z0-9-]+)?:([a-z0-9-]+)$"
        },
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9:_-]+$"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "coordinates"
      ],
      "pbj": {
        "type": "message-ref",
        "rule": "single"
      }
    }
  },
  "required": [
    "_schema",
    "request",
    "response_id",
    "created_at"
  ],
  "definitions": {
    "request": {
      "$ref": "https://schemas.gdbots.io/gdbots/pbjx/mixin/request/1-0-0.json"
    }
  },
  "additionalProperties": false
}

The fields on for request-failed-response are rendered first. It's nice if the schema def matches the order in which the fields are rendered/serialized.

Add schemas for event store and search

Use draft-04 reference for json-schema

• Rather than point to latest, let's pin it to draft-04 on the generated schema.
• Put the id first and append #.
• The base url for json-schema should be schema store domain + /json-schema/ + schemaid.. see below. and http, not https (gh pages doesn't support https currently)

  "id": "http://schemas.gdbots.io/json-schema/gdbots/contexts/user-agent/1-0-0.json#",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",