@avocode/octopus-schema

Octopus Schema

The file openapi.json describes the Octopus document format in the OpenAPI v3.1 RC format. "Octopus" in this context refers to the JSON representation of a single design file artboard content.

The specification includes a definition for a fake GET / endpoint which returns the OctopusDocument root schema. This allows the linter to properly detect unused schema components.

Versioning

• The described Octopus format minor version is specified in openapi.json#/info/version.
• The version of this package MUST reflect the minor version of Octopus format described.
• The patch version component reflects the iteration of the schema for the specific Octopus format minor version. Design file format-specific patch versions are not reflected in this specification. Any changes made to the specification based on format-specific octopus patches simply lead to a sequential increase of the patch version component of this package.

Usage

This repository is released to NPM as @avocode/octopus-schema.

yarn add --exact --dev @avocode/octopus-schema

TypeScript

1. The main module of the library is the TypeScript type.

import { Octopus } from '@avocode/octopus-schema'

function processOctopus(data: Octopus.OctopusDocument) {
  if (data['layer']) {
    data['layers'].forEach((layerData) => {
      processLayer(layerData)
    })
  }
}

function processLayer(layerData: Octopus.Layer) {
  console.log(layerData)
}

OpenAPI

1. Copy the OpenAPI file from the library to your build artifacts during your build step.

cp $(node -e 'console.log(require.resolve("@avocode/octopus-schema/openapi.json"))') ./octopus.json

1. Reference the schemas from the octopus.json file.

{
  "info": {},
  "components": {
    "OctopusDocument": "./octopus.json#/components/schemas/OctopusDocument"
  }
}

How Is This Specification Used in Avocode

• The Open Design API specification includes this Octopus format specification.
• The internal Octopus libraries and workers should use types from this package.

Development

• The openapi.json file is edited by hand.
• TypeScript type file is auto-generated from the openapi.json specification via openapi-typescript which can be run as yarn build:ts.
• The repository is linted via Prettier which can be run as yarn lint:prettier (or as yarn lint:prettier -w for auto-fix).
• The OpenAPI specification (openapi.json) is validated via Spectral which can be run as yarn validate:openapi.

Release Process

yarn publish

• The command asks for the version bump.
  • The major and minor version components must reflect the Octopus format version described by the release. The patch version component is arbitrary. This is automatically checked.

Issues

• The openapi.json#/openapi version field states the version of 3.0.2 instead of 3.1.x which allows the Spectral linter to process the file. Support for OpenAPI v3.1 is not currently included in the linter. (The feature from v3.1 which is important for us is the ability to specify siblings of $ref types. This allows us to reuse types while overriding their descriptions.)