Struct fog_pack::Schema

pub struct Schema { /* fields omitted */ }

Struct holding the validation portions of a schema. Can be used for validation of a document or entry.

Schema are a special type of Document that describes the format of other documents and their associated entries. They also include recommended compression settings for documents adhering to them, and optionally may include compression dictionaries for improved compression.

Much like how many file formats start with a "magic number" to indicate what their format is, any document adhering to a schema uses the schema's document hash in the empty field. For example, a schema may look like:

{
    "": core_schema.hash().clone(),
    "name": "Simple Schema",
    "req": {
        "title": { "type": "Str", "max_len": 255},
        "text": { "type": "Str" }
    }
}

A document that uses this "Basic Schema" would look like:

{
    "": basic_schema.hash().clone(),
    "title": "Example Document",
    "text": "This is an example document that meets a schema"
}

Schema Document Format

The most important concept in a schema document is the validator. A validator is a fog-pack object containing the validation rules for a particular part of a document. It can directly define the rules, or be aliased and used throughout the schema document. Validators are always one of the base fog-pack value types, or allow for several of them. See the Validation Language for more info.

At the top level, a schema is a validator for an object but without support for the in, nin, comment, default, or query optional fields. Instead, it supports a few additional optional fields for documentation, entry validation, and compression:

• name: A brief string to name the schema.
• description: A brief string describing the purpose of the schema.
• version: An integer for tracking schema versions.
• entries: An object containing validators for each allowed Entry that may be attached to a Document following the schema.
• types: An object containing aliased validators that may be referred to
• anywhere within the schema
• doc_compress: Optionally specifies recommended compression settings for Documents using the schema.
• entries_compress: Optionally specifies recommended compression settings for entries attached to documents using the schema.

Implementations

impl Schema

pub fn from_doc(doc: Document) -> Result<Self>

pub fn hash(&self) -> &Hash

pub fn encode_doc(&mut self, doc: Document) -> Result<Vec<u8>>

Encode the document and write it to an output buffer. Schema compression defaults are used unless overridden by the Document. This will fail if the document's schema hash doesn't match this schema, or validation fails.

Panics

Panics if the underlying zstd calls return an error, which shouldn't be possible. Also panics if the document somehow became larger than the maximum allowed size, which should be impossible with the public Document interface.

pub fn trusted_decode_doc(
    &mut self,
    buf: &mut &[u8],
    hash: Option<Hash>
) -> Result<Document>

Read a document from a byte slices, trusting the origin of the slice and doing as few checks as possible when decoding. It fails if there isn't a valid fog-pack value, The compression isn't valid, the slice terminates early, or if the document isn't using this schema.

Rather than compute the hash, the document hash can optionally be provided. If integrity checking is desired, provide no hash and compare the expected hash with the hash of the resulting document.

The only time this should be used is if the byte slice is coming from a well-trusted location, like an internal database.

pub fn decode_doc(&mut self, buf: &mut &[u8]) -> Result<Document>

Read a document from a byte slice, performing the full set of validation checks when decoding. Success guarantees that the resulting Document is valid and passed schema validation, and as such, this can be used with untrusted inputs.

Validation checking means this will fail if:

• The data is corrupted or incomplete
• The data isn't valid fogpack
• The data doesn't use this schema
• The data doesn't adhere to this schema
• The compression is invalid or expands to larger than the maximum allowed size
• Any of the attached signatures are invalid

pub fn encode_entry(&mut self, entry: Entry) -> Result<Checklist<Vec<u8>>>

Encodes an Entry's contents and returns a Checklist containing the encoded byte vector. The entry's parent hash and field are not included. This will fail if entry validation fails, or the entry's field is not covered by the schema.

pub fn trusted_decode_entry(
    &mut self,
    buf: &mut &[u8],
    doc: Hash,
    field: String,
    hash: Option<Hash>
) -> Result<Entry>

Read an Entry from a byte slice, trusting the origin of the slice and doing as few checks as possible when decoding. It fails if there isn't a valid fog-pack value, the compression isn't valid, or the slice terminates early.

Rather than compute the hash, the entry's hash can optionally be provided. If integrity checking is desired, provide no hash and compare the expected hash with the hash of the resulting entry.

The only time this should be used is if the byte slice is coming from a well-trusted location, like an internal database.

pub fn decode_entry(
    &mut self,
    buf: &mut &[u8],
    doc: Hash,
    field: String
) -> Result<Checklist<Entry>>

Read an Entry from a byte slice, performing a full set of validation checks when decoding. On successful validation of the entry, a Checklist is returned, which contains the decoded entry. Processing the checklist with this schema will complete the checklist and yield the decoded Entry.

pub fn check_item(&self, doc: &Document, item: &mut ChecklistItem) -> Result<()>

Checks a document against a given ChecklistItem. Marks the item as done on success. Fails if validation fails.

A ChecklistItem comes from a Checklist.

pub fn decode_query(&self, buf: &mut &[u8]) -> Result<Query>

Read a Query from a byte slice, performing a set of checks to verify the query is allowed by this schema. It can fail if the encoded query doesn't match allowed validator semantics, or if the query is not permitted by the schema.