juit-api-schema v0.1.0

Juit Schemas

This repositotry contains a number of JSON schemas which will be used to validate the various requests and responses in the Juit APIs.

Index

• Library use
• Documentation helper
• Main schemas
  • Core Types Schema
    • https://json-schema.juit.com/core/v1.0
    • https://json-schema.juit.com/core/v1.0#created
    • https://json-schema.juit.com/core/v1.0#ean
    • https://json-schema.juit.com/core/v1.0#id
    • https://json-schema.juit.com/core/v1.0#modified
    • https://json-schema.juit.com/core/v1.0#user
  • Rating
    • https://json-schema.juit.com/rating/v1.0
    • https://json-schema.juit.com/rating/v1.0#create
    • https://json-schema.juit.com/rating/v1.0#update
  • User
    • https://json-schema.juit.com/user/v1.0

Library use

As a module this project exports a few functions to help validating objects against our schemas

• validate(ref, data)\ strictly validate the specified data according to the schema identified by the given ref

• strip(ref, data)\ loosely validate and strip optional properties from the specified data according to the schema identified by the given ref

• with(baseRef)\ return the two above-mentioned functions where each ref is resolved against the given baseRef before validation.

const schemas = require('@oetkerdigital/juit-api-schema')

// strictly validate using https://json-schema.juit.com/rating/v1.0#create
schema.validate('https://json-schema.juit.com/rating/v1.0#create', ...)

// loosely validate and strip extra properties using https://json-schema.juit.com/rating/v1.0
schema.strip('https://json-schema.juit.com/rating/v1.0', ...)

// or alternatively exactly as above but resolving relative to a base ref
const ratingSchema = schemas.with('https://json-schema.juit.com/rating/v1.0')
ratingSchema.validate('#create', ...) // uses https://json-schema.juit.com/rating/v1.0#create
ratingSchema.strip('#', ...)          // uses https://json-schema.juit.com/rating/v1.0

Documentation helper

This package exposes also a documentation helper which can inject some nice documentation in MarkDown documents (like, above!).

You can find this in the docco binary (docco.js). This helper will parse a MarkDown document with HandleBars and will provide the following helpers:

• {{anchor '...'}}\ prepares an anchor linkt to another position in this document
  • e.g. {{anchor 'Foo Bar'}} becomes [Foo Bar](#foo-bar)
• {{schema 'http://....'}}\ outputs the full documentation for the schema with the specified ID
• {{properties 'http://....'}}\ outputs only the properties documentation for the schema with the specified ID

See the template from which this document was generated for an example on how those helpers work.

Core Types Schema

https://json-schema.juit.com/core/v1.0

A schema defining our core types

This schema is intentionally empty, providing only common definitions to other schemas

https://json-schema.juit.com/core/v1.0#created

The timestamp indicating when this object was originally created

• type: string
• format: date-time

https://json-schema.juit.com/core/v1.0#ean

The EAN-13 code of an item

This is normally used to identify our sellable products, as they all have EAN-13 codes

• type: string
• format: ean13

https://json-schema.juit.com/core/v1.0#id

The primary UUID identifying this object

This usually identifies our PRIMARY KEY in our database tables

• type: string
• format: uuid

https://json-schema.juit.com/core/v1.0#modified

The timestamp indicating when this object was last modified

• type: string
• format: date-time

https://json-schema.juit.com/core/v1.0#user

The UUID referring to the user associated this object

Examples of this are the user who created an order, the user who submitted a rating, ...

• type: string
• format: uuid

Rating

https://json-schema.juit.com/rating/v1.0

A user rating for an item

• type: object

Properties

• $id The primary UUID identifying this object
  • type: string, format: uuid, required
  • references https://json-schema.juit.com/core/v1.0#id
• $user The UUID referring to the user associated this object
  • type: string, format: uuid, required
  • references https://json-schema.juit.com/core/v1.0#user
• $created The timestamp indicating when this object was originally created
  • type: string, format: date-time, required
  • references https://json-schema.juit.com/core/v1.0#created
• $modified The timestamp indicating when this object was last modified
  • type: string, format: date-time, required
  • references https://json-schema.juit.com/core/v1.0#modified
• ean The EAN-13 code of an item
  • type: string, format: ean13, required
  • references https://json-schema.juit.com/core/v1.0#ean
• score The score (from 0 to 4) for this rating
  • type: number, minimum: 0, maximum: 5, required
• comment The comment submitted with this rating
  • type: string or null, maxLength: 1024, optional

https://json-schema.juit.com/rating/v1.0#create

The schema to validate ratings creations

• type: object

Properties

• ean The EAN-13 code of an item
  • type: string, format: ean13, required
  • references https://json-schema.juit.com/core/v1.0#ean
• score The score (from 0 to 4) for this rating
  • type: number, minimum: 0, maximum: 5, required
• comment The comment submitted with this rating
  • type: string or null, maxLength: 1024, optional

https://json-schema.juit.com/rating/v1.0#update

The schema to validate updates to ratings

• type: object

Properties

• score The score (from 0 to 4) for this rating
  • type: number, minimum: 0, maximum: 5, optional
• comment The comment submitted with this rating
  • type: string or null, maxLength: 1024, optional

User

https://json-schema.juit.com/user/v1.0

A user

• type: string

Properties

• $id The primary UUID identifying this object
  • type: string, format: uuid, required
  • references https://json-schema.juit.com/core/v1.0#id
• first_name The first (given) name of the user
  • type: string, minLength: 1, maxLength: 128, required
• last_name The last (family) name of the user
  • type: string, minLength: 1, maxLength: 128, required