@swagger-api/apidom-ns-json-schema-draft-4

@swagger-api/apidom-ns-json-schema-draft-4

@swagger-api/apidom-ns-json-schema-draft-4 contains ApiDOM namespace specific to JSON Schema Draft 4 specification.

You might come across references to Draft 5 a.k.a. Wright Draft 00 (core, validation and hyper-schema vocabularies). There is no Draft 5 release of JSON Schema. Draft 5 refers to a no-change revision of the Draft 4 release. It does not add, remove, or change any functionality. It only updates references, makes clarifications, and fixes bugs. This package implements Draft 4 + no-change revision of Draft 5.

Installation

You can install this package via npm CLI by running the following command:

 $ npm install @swagger-api/apidom-ns-json-schema-draft-4

JSON Schema Draft 4 namespace

JSON Schema Draft 4 namespace consists of number of elements implemented on top of primitive ones.

import { createNamespace } from '@swagger-api/apidom-core';
import jsonShemaDraft4Namespace from '@swagger-api/apidom-ns-json-schema-draft-4';

const namespace = createNamespace(jsonShemaDraft4Namespace);

const objectElement = new namespace.elements.Object();
const jsonSchemaElement = new namespace.elements.JSONSchemaDraft4();

When namespace instance is created in this way, it will extend the base namespace with the namespace provided as an argument.

Elements from the namespace can also be used directly by importing them.

import { JSONSchemaElement, JSONReferenceElement, LinkDescriptionElement, MediaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const jsonSchemaElement = new JSONSchemaElement();
const jsonReferenceElement = new JSONReferenceElement();
const linkDescriptionElement = new LinkDescriptionElement();
const mediaElement = new MediaElement();

Predicates

This package exposes predicates for all higher order elements that are part of this namespace.

import { isJSONSchemaElement, JSONSchemaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const jsonSchemaElement = new JSONSchemaElement();

isJSONSchemaElement(jsonSchemaElement); // => true

Traversal

Traversing ApiDOM in this namespace is possible by using visit function from apidom package. This package comes with its own keyMap and nodeTypeGetter. To learn more about these visit configuration options please refer to @swagger-api/apidom-ast documentation.

import { visit } from '@swagger-api/apidom-core';
import { JSONSchemaElement, keyMap, getNodeType } from '@swagger-api/apidom-ns-json-schema-draft-4';

const element = new JSONSchemaElement();

const visitor = {
  JSONSchemaDraft4Element(jsonSchemaElement) {
    console.dir(jsonSchemaElement);
  },
};

visit(element, visitor, { keyMap, nodeTypeGetter: getNodeType });

Refractors

Refractor is a special layer inside the namespace that can transform either JavaScript structures or generic ApiDOM structures into structures built from elements of this namespace.

Refracting JavaScript structures:

import { MediaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const object = {
  binaryEncoding: 'base64',
  type: 'image/png',
};

MediaElement.refract(object); // => MediaElement({ binaryEncoding, type })

Refracting generic ApiDOM structures:

import { ObjectElement } from '@swagger-api/apidom-core';
import { MediaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const objectElement = new ObjectElement({
  binaryEncoding: 'base64',
  type: 'image/png',
});

MediaElement.refract(objectElement); // => MediaElement({ binaryEncoding = 'base64', type = 'image/png' })

Refractor plugins

Refractors can accept plugins as a second argument of refract static method.

import { ObjectElement } from '@swagger-api/apidom-core';
import { MediaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const objectElement = new ObjectElement({
  binaryEncoding: 'base64',
  type: 'image/png',
});

const plugin = ({ predicates, namespace }) => ({
  name: 'plugin',
  pre() {
      console.dir('runs before traversal');
  },
  visitor: {
    MediaElement(mediaElement) {
      mediaElement.type = 'image/gif';
    },
  },
  post() {
      console.dir('runs after traversal');
  },
});

MediaElement.refract(objectElement, { plugins: [plugin] }); // => MediaElement({ binaryEncoding = 'base64', type = 'image/gif' })

You can define as many plugins as needed to enhance the resulting namespaced ApiDOM structure. If multiple plugins with the same visitor method are defined, they run in parallel (just like in Babel).

Replace Empty Element plugin

This plugin is specific to YAML 1.2 format, which allows defining key-value pairs with empty key, empty value, or both. If the value is not provided in YAML format, this plugin compensates for this missing value with the most appropriate semantic element type.

import { parse } from '@swagger-api/apidom-parser-adapter-yaml-1-2';
import { refractorPluginReplaceEmptyElement, JSONSchemaElement } from '@swagger-api/apidom-ns-json-schema-draft-4';

const yamlDefinition = `
$schema: 'http://json-schema.org/draft-04/schema#'
additionalProperties:
`;
const apiDOM = await parse(yamlDefinition);
const jsonSchemaElement = JSONSchemaElement.refract(apiDOM.result, {
  plugins: [refractorPluginReplaceEmptyElement()],
});

// =>
// (JSONSchemaDraft4Element
//   (MemberElement
//     (StringElement)
//     (StringElement))
//   (MemberElement
//     (StringElement)
//     (JSONSchemaDraft4Element)))

// => without the plugin the result would be as follows:
// (JSONSchemaDraft4Element
//   (MemberElement
//     (StringElement)
//     (StringElement))
//   (MemberElement
//     (StringElement)
//     (StringElement)))

Implementation progress

Only fully implemented specification objects should be checked here.

• JSON Schema Object
• JSON Reference Object
• Link Description Object
• Media Object

Changelog

0.96.0 (2024-02-28)

Bug Fixes

• core: assign unique ID to elements only when missing (#3841) (89af0a9), closes #3840
• core: retain meta & attributes during refracting (#3843) (a7aac32), closes #3842
• ns-ads: retain meta & attributes during refracting (#3857) (333550e), closes #3842
• ns-asyncapi-2: retain meta & attributes during refracting (#3858) (e3b1848), closes #3842
• ns-json-schema: retain meta & attributes during refracting (#3862) (99c3eb8), closes #3842
• ns-openapi-2: retain meta & attributes during refracting (#3844) (b243110), closes #3842
• ns-openapi-3-0: retain meta & attributes during refracting (#3859) (abefa88), closes #3842
• ns-openapi-3-1: retain meta & attributes during refracting (#3861) (e960a76), closes #3842
• ns-workflows-1: retain meta & attributes during refracting (#3860) (7e40336), closes #3842
• playground: fix bug related to instantiating parser (#3851) (9b23628)
• reference: add support for external cycles detection in AsyncAPI 2.x dereference strategy (#3872) (910a974), closes #3863
• reference: add support for external cycles detection in OpenAPI 2.0 dereference strategy (#3871) (5a2141d), closes #3863
• reference: add support for external cycles detection in OpenAPI 3.0.x dereference strategy (#3870) (0735471), closes #3863
• reference: add support for external cycles detection in OpenAPI 3.1.0 dereference strategy (#3873) (9cd15ff), closes #3863

Features

• apidom-converter: add infoSummaryRefractorPlugin (#3848) (1f0a39c), closes #3697
• apidom-converter: add licenseIdentifierRefractorPlugin (#3854) (b28cafb), closes #3697
• apidom-converter: add securitySchemeTypeRefractorPlugin (#3802) (2666194)
• converter: add convenient toolbox utils (#3816) (ec8fa05)
• converter: add securityRequirementsArrayRefractorPlugin (88b9451)
• core: add mechanism for left shallow merge (#3849) (3334c6b), closes #3845
• core: add mechanism for right shallow merge (#3846) (2059f28), closes #3845
• core: customize meta & attributes merges for deepmerge function (#3855) (1e94924), closes #3853
• ns-openapi-3-0: add Security Schema Object predicate (#3810) (9b09658)
• ns-openapi-3-0: include hasElementSourceMap in toolbox (#3815) (e103eb4)
• ns-openapi-3-1: add Security Schema Object predicate (#3811) (bf6702a)
• ns-openapi-3-1: include hasElementSourceMap in toolbox (#3814) (3979541)