Skip to main content

Schemas

  • Schemas are used to describe and validate the format in which data is published
  • Schemas are identified by their schema id
  • Schemas have a name, a description and a number of fields
🌩️Requirement SC1

The name of a schema MUST match the regular expression ^[A-Za-z]{1}[A-Za-z0-9_]{0,62}[A-Za-z0-9]{1}$

  • The name of a schema MUST be at most 64 characters long
  • It begins with a letter
  • It uses only alphanumeric characters, digits and the underscore character ( _ )
  • It doesn't end with an underscore
🌩️Requirement SC2

The description of a schema MUST consist of unicode characters and MUST be at most 256 characters long

🌩️Requirement SC3

A schema MUST have at most 1024 fields

Fields​

  • A field is defined by
    • field name
    • field type
🌩️Requirement SC4

The field name MUST match the regular expression ^[A-Za-z]{1}[A-Za-z0-9_]{0,63}$

  • The field name MUST be at most 64 characters long
  • It begins with a letter
  • It uses only alphanumeric characters, digits and the underscore character ( _ )
🌩️Requirement SC5

The field type MUST be one of:

  • bool
  • int
  • float
  • bytes
  • str
  • relation
  • relation list
  • pinned relation
  • pinned relation list

bool fields​

  • Encode a boolean value

int fields​

  • Encode a signed 64 bit integer number

float fields​

  • Encode a 64 bit floating point number

bytes fields​

  • Encode a bytes (u8) string

str fields​

  • Encode a text string
🌩️Requirement SC6

str fields MUST use unicode encoding

relation fields​

  • Encode a relation to one or many other documents
  • There are four kinds of relation fields
    • Relations represent the whole referenced document through their document id
      • relation: reference to a single document
      • relation list: a list of references to documents
    • Pinned relations point at immutable versions of documents through their document view ids
      • pinned relation: reference to a single document view.
      • pinned relation list: a list of references to document views
🌩️Requirement SC7

All relation fields MUST define a schema that all referenced documents must conform to

🌩️Requirement SC8

relation fields MAY be self-referential in that their target is of the same schema. Self-referential relations MAY be interpreted as document ordering in queries

System and Application Schemas​

  • System schemas are defined as part of the p2panda specification
    • The format of system schema operations can be validated by their CDDL definitions
  • Application schemas are published by developers
    • They are used to validate the format of application specific data
    • All developers can create new application schemas by publishing documents of the SchemaDefinition and SchemaFieldDefinition system schemas
    • They are published as reusable data schemas and can be used in many applications
    • System schemas may have unique procedures for reduction, reconciliation and persistence of their documents

Schema ID​

  • Schema ids are strings that uniquely identify a schema
  • Every system schema's schema id is given in that schema's section below
    • They always start with the schema's name in snake case
    • Then an underscore separator
    • Then the letter v, followed by the schema's version number as an integer
    • Example: key_group_v1
  • Application schema ids are constructed from the schema's name and document view id
    • They consist of sections separated by an underscore
    • The first section is the name, which must have 1-64 characters, must start with a letter and must contain only alphanumeric characters and underscores
    • The remaining sections are the document view id of the schema's schema_definition_v1 document, represented as alphabetically sorted hex-encoded operation ids, separated by underscores.
    • Example profile_picture_0020c65567ae37efea293e34a9c7d13f8f2bf23dbdc3b5c7b9ab46293111c48fc78b
  • As application schema ids can potentially grow very large the schema hash id is an alternative identifier with limited size
    • Unless a limited-size identifier is required, the regular schema id should be preferred as it's not possible to reconstruct the schema document from the schema hash id
    • The schema hash id is constructed by concatenating
      • The schema's name
      • Two underscore characters (__)
      • The schema's document view hash id
      • Example: profile_picture__0020c65567ae37efea293e34a9c7d13f8f2bf23dbdc3b5c7b9ab46293111c48fc78b
🌩️Requirement SC9

The name string in an application schema which MUST have 1-64 characters, MUST start with a letter and MUST contain only alphanumeric characters and underscores.

System Schemas​

Schema Definition​

  • Schema id: schema_definition_v1
  • Used to publish application schemas
  • Fields:
    • name: string
    • description: string
    • fields: a pinned relation list referencing schema_field_definition_v1 documents

Schema Field Definition​

  • Schema id: schema_field_definition_v1
  • Defines individual fields for schema definitions
  • Fields:
    • name: string
    • type: string
🌩️Requirement SC10

schema_field_definition_v1 type field MUST be one of

  • bool: boolean
  • int: integer number
  • float: floating point number
  • bytes: bytes string
  • str: text string
  • relation(<schema_id>): reference to a document
  • relation_list(<schema_id>): a list of references to documents
  • pinned_relation(<schema_id>): reference to a document view
  • pinned_relation_list(<schema_id>): a list of references to document views

All relation field types need to specify a schema

  • <schema_id> in the above listing needs to be a valid schema id
  • Documents referenced by any relation field, to which this schema field definition applies, need to be of this schema
  • E.g. if you are publishing an operation to update a field with the type relation(key_group_v1), the field value needs to be the document id of a key_group_v1 document