@types endpoint specs

[ebrehault]

Just to keep somewhere what we discussed at Barcelona Sprint with @tisto and @vangheem:

• basic fields: provided by JSON Schema
• fieldsets: provided by JSON Schema (nested schemas)
• validation: partly provided by JSON Schema (simple validation)
• actions: provided by JSON Schema (hyper-schema links)
• read-only fields: provided by JSON Schema
• vocabularies: provided by JSON Schema
• widgets (just the id): NOT PROVIDED
• help messages: NOT PROVIDED
• placeholders: NOT PROVIDED
• master-slave: NOT PROVIDED
• subchema (=datagrids): ?

[tisto]

Just FYI: I already documented our discussion from the sprint here: #89

[esteele]

I've been working on implementing this in https://github.com/pyrenees/plone.dexterity/tree/master/plone/dexterity/serialize. Things need to be reorganized a bit, but most of it's there.

{
  "@type": "Todo",
  "parent": {
    "@type": "Plone Site",
    "@id": "/plone",
    "title": "Demo Site",
    "description": "Awww yeah..."
  },
  "@id": "/plone/obj1",
  "schema": {
    "properties": {
      "invariants": [],
      "created": {
        "readonly": "False",
        "type": "zope.schema.Datetime",
        "description": "The date and time that an object is created. \nThis is normally set automatically.",
        "required": "True",
        "title": "Creation Date"
      },
      "fieldsets": {
        "other": {
          "properties": {
            "assigned_to": {
              "readonly": "False",
              "type": "zope.schema.TextLine",
              "description": "The person who needs to complete the task.",
              "min_length": "0",
              "title": "Assigned To",
              "default": "",
              "required": "False"
            },
            "notes": {
              "readonly": "False",
              "type": "zope.schema.Text",
              "description": "Classified notes on about task",
              "min_length": "0",
              "title": "Notes",
              "default": "",
              "required": "False"
            }
          },
          "label": "Additional Information"
        }
      },
      "schemas": {
        "IDublinCore": {
          "based_on": [],
          "invariants": "",
          "fields": [
            "created",
            "modified"
          ],
          "name": "IDublinCore"
        },
        "ITodo": {
          "based_on": [
            "plone.example.todo.IExampleBase"
          ],
          "invariants": "",
          "fields": [
            "done",
            "assigned_to",
            "notes"
          ],
          "name": "ITodo"
        }
      },
      "done": {
        "readonly": "False",
        "type": "zope.schema.Bool",
        "description": "Has the task been completed?",
        "title": "Done",
        "default": "False",
        "required": "False"
      },
      "modified": {
        "readonly": "False",
        "type": "zope.schema.Datetime",
        "description": "The date and time that the object was last modified in a\nmeaningful way.",
        "required": "True",
        "title": "Modification Date"
      }
    },
    "title": "Todo",
    "type": "object"
  },
  "created": null,
  "assigned_to": "",
  "done": false,
  "title": "It's a todo!",
  "modified": null,
  "UID": "355b0b3789ca445c9090f7fb1fde8cec"
}

[esteele]

@ebrehault Can you elaborate on the placeholders/help messages items? Are these currently exposed in dexterity/zope.schema?

[ebrehault]

@esteele The help message is basically the description attribute of our schema fields.
Placeholders are not managed in zope.schema nor dexterity. I guess we can skip it for now.

[fbessou]

Nested schemas are just custom properties of JSON Schemas which are available for referencing. But they are only seen as schemas if they are referenced. For example :

{
  "nested": {
    "type": "string",
    "minLength": 2
  },
  "properties": {
    "name": {"$ref":"#/nested"}
  }
}

I propose to use the following structure as it would not interfere with the way JSON Schema is intended to be used.

{
  "$schema": "http://json-schema.org/draft-04/hyper-schema#",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "creditCardNumber": {
      "type": "string",
      "pattern": "[0-9]{13,16}"
    }
  },
  "fieldsets": [{
    "id": "part_1",
    "title": "Registration",
    "fields": ["username", "email"]
  },
  {
    "id": "part_2",
    "title": "Payment",
    "fields": ["creditCardNumber"]   
  }],
  "required": ["username", "email", "creditCardNumber"],
  "links": [{
    "title": "Cancel",
    "description": "Cancel the transaction",
    "href": "test",
    "rel": "action"
  },
  {
    "title": "Cancel",
    "description": "Cancel the transaction",
    "href": "somewhere",
    "rel": "action"
  }]
}

Where fieldsets is a custom property which will not be processed by validators.