2022-09-01 18:32:26 -05:00
..
2022-09-01 18:32:26 -05:00
2022-07-14 18:36:23 -05:00
2022-07-14 18:36:23 -05:00
2022-07-14 18:36:23 -05:00
wip
2022-08-04 20:34:54 -05:00
2022-07-14 18:36:23 -05:00
2022-07-14 18:36:23 -05:00
2022-07-14 18:36:23 -05:00

ADX Schemas Library

This is a toolkit for validating ADX Schemas. See DESIGN.md for more information about how ADX Schemas work.

npm install @adxp/schemas

Usage

import { AdxSchemas } from '@adxp/schemas'

// example schema: "Zeets"
const ublogSchema = {
  $type: 'adxs-record',
  author: 'blueskyweb.xyz',
  name: 'Ublog',
  locale: {
    en: {
      nameSingular: 'Micro-blog Post',
      namePlural: 'Micro-blog Posts',
    }
  },
  schema: {
    type: 'object',
    required: ['text', 'createdAt'],
    properties: {
      text: { type: 'string', maxLength: 256 },
      createdAt: { type: 'string', format: 'date-time' }
    }
  }
}

// create your schemas collection
const schemas = new AdxSchemas()
schemas.add(ublogSchema)
schemas.add(pollSchema) // pollSchema's definition not included for brevity

// create a validator
const ublogValidator = schemas.createRecordValidator({
  type: 'UBlog', // base type (required). Can be an array.
  ext: ['Poll'] // extension types (optional)
})

// now we can validate records with...
ublogValidator.validate({/*..*/}) // => returns a result
ublogValidator.isValid({/*..*/}) // => returns a boolean
ublogValidator.assertValid({/*..*/}) // => returns a result on success, throws on fail

Some examples of validation:

// a valid record
// --------------
const res1 = ublogValidator.validate({
  $type: 'blueskyweb.xyz:UBlog',
  text: 'Hello, world!',
  createdAt: '2022-06-28T22:17:33.459Z'
})
res1.compatible     // => true
res1.valid          // => true
res1.fullySupported // => true
res1.error          // => undefined
res1.fallbacks      // => []

// an invalid record
// -----------------
const res2 = ublogValidator.validate({
  $type: 'blueskyweb.xyz:UBlog',
  text: 'Hello, world!',
  createdAt: 12345 // <-- wrong type!
})
res2.compatible     // => true
res2.valid          // => false
res2.fullySupported // => false
res2.error          // => `Failed blueskyweb.xyz:UBlog validation for #/properties/createdAt/type: must be string`
res2.fallbacks      // => []

// an unsupported record type
// --------------------------
const res3 = ublogValidator.validate({
  $type: 'other.org:Fret', // <-- not one of our declared schemas!
  text: 'Hello, world!',
  createdAt: '2022-06-28T22:17:33.459Z'
})
res3.compatible     // => false
res3.valid          // => false
res3.fullySupported // => false
res3.error          // => `Record type other.org:Fret is not supported`
res3.fallbacks      // => []

// a valid record with an extension
// --------------------------------
const res4 = ublogValidator.validate({
  $type: 'blueskyweb.xyz:UBlog',
  text: 'Hello, world!',
  createdAt: '2022-06-28T22:17:33.459Z',
  $ext: {
    'blueskyweb.xyz:Poll': {
      $required: true,
      $fallback: {
        en: 'This zeet includes a poll which this application does not support.',
      },
      question: "Do you like ADX's schemas system?",
      answers: ['yes', 'no', 'eh'],
    },
  },
})
res4.compatible     // => true
res4.valid          // => true
res4.fullySupported // => true
res4.error          // => undefined
res4.fallbacks      // => []

// a valid record with an unsupported-but-optional extension
// ---------------------------------------------------------
const res5 = ublogValidator.validate({
  $type: 'blueskyweb.xyz:UBlog',
  text: 'Hello, world!',
  createdAt: '2022-06-28T22:17:33.459Z',
  $ext: {
    'other.org:Poll': { // <-- we don't understand this type
      $required: false, // <-- ...but it's not required
      $fallback: {
        en: 'This zeet includes a poll which this application does not support.',
      },
      question: "Do you like ADX's schemas system?",
      answers: ['yes', 'no', 'eh'],
    },
  },
})
res5.compatible     // => true
res5.valid          // => true
res5.fullySupported // => false
res5.error          // => undefined
res5.fallbacks      // => ['This zeet includes a poll which this application does not support.']