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
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
The description of a schema MUST consist of unicode characters and MUST be at most 256 characters long
A schema MUST have at most 1024 fields
Fieldsβ
- A field is defined by
- field name
- field type
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 (
_
)
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
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
- Relations represent the whole referenced document through their document id
All relation fields MUST define a schema that all referenced documents must conform to
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
andSchemaFieldDefinition
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
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
: stringdescription
: stringfields
: a pinned relation list referencingschema_field_definition_v1
documents
Schema Field Definitionβ
- Schema id:
schema_field_definition_v1
- Defines individual fields for schema definitions
- Fields:
name
: stringtype
: string
schema_field_definition_v1
type field MUST be one of
bool
: booleanint
: integer numberfloat
: floating point numberbytes
: bytes stringstr
: text stringrelation(<schema_id>)
: reference to a documentrelation_list(<schema_id>)
: a list of references to documentspinned_relation(<schema_id>)
: reference to a document viewpinned_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 akey_group_v1
document