specification.md

Scriptappy specification

A specification for Javascript APIs

Version 1.1.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Table of Contents

• Specification
  • Schema
    • Root Object
    • Info Object
    • Entity Base
    • Availability Object
    • Deprecated Object
    • Entity Tier 0
    • Entity Tier 1
    • Entity Tier 2
    • Entity Tier 3
    • Entity Tier 4
    • Alias
    • Enum
    • Literal
    • Module
    • Object
    • Namespace
    • Function
    • Class
    • Constructor Object
    • Interface
    • Event
    • Array
    • Union

Definitions

Entity

An entity refers to an 'endpoint' in the API, e.g. a method, class, module, namespace etc.

Entity tier

The different entities are separated into tiers to make referencing easier. When a tier is referenced, any of the entities in that tier are allowed in place of the tier.

Specification

Schema

Root object

Field	Type	Description
spec	const 1.1.0	REQUIRED. The specification version the document uses.
info	Info object	REQUIRED. Metadata about the API.
examples	Array<string>	Examples showing how to use this API.
entries	Map<string, Entity Object>	REQUIRED. An object holding the entry points available for the API.
definitions	Map<string, Entity Object>	Additional entities reachable through the entry points.

Example

{
  spec: '1.1.0',
  info: { /* info object */ },
  entries: {
    getName: { /* entity object */ }
  },
  definitions: {
    Name: { /* entity object */ }
  }
}

Info Object

Field	Type	Description
name	string	Name of the API.
description	string	Description of the API.
version	string	REQUIRED. Version of the API.
license	string	REQUIRED. SPDX license identifier for the API.

Example

{
  "name": "PaymentAPI",
  "description": "Pay me!",
  "version": "1.3.0",
  "license": "MIT"
}

Entity Base

Field	Type	Description
description	string	A description of the entity.
stability	'experimental' | 'stable' | 'locked'	The stability of the entity.
availability	Availability Object	The availability of the entity.
examples	Array<string>	Examples showing how to use this entity.
type	string	The type of this entity.
name	string	Name of this entity.
optional	boolean	Optionality of this entity. Used to indicate when the entity is optional as a method parameter or an object entry.
nullable	boolean	Nullability of this entity. Used to indicate when the entity is nullable as a method parameter or an object entry.
variable	boolean	Variability of this entity. Used to indicate when the entity is repeatable as a method parameter.
generics	Array<Entity Tier 3>	Generic types.
defaultValue	number | boolean | string	Default value for this entity. Used when the entity is optional.
templates	Array<Named Object | Entity Tier 3>	The generic templates for this entity.

Example

{
  "type": "number"
  "description": "Get the current amount",
  "stability": "stable",
  "availability": {
    "since": "1.1.0"
  },
  "optional": true,
  "defaultValue": 13
}

Availability Object

Field	Type	Description
since	string	API version from which owning entity is available.
deprecated	boolean | Deprecated Object	Current deprecation status of owning entity.

Example

{
  "since": "1.0.0",
  "deprecated": false
}

Deprecated Object

Field	Type	Description
since	string	REQUIRED. API version from which owning entity is considered deprecated.
description	string	A short description and a recommendation on what to use instead of the deprecated entity.

Example

{
  "since": "1.4.5",
  "description": "Deprecated since 1.4.5, use something else instead :P."
}

Entity Tier 0

This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:

Module

Entity Tier 1

This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:

Namespace

Entity Tier 2

This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:

Alias | Enum | Class | Interface

Entity Tier 3

This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:

Entity Base | Literal | Object | Function | Array | Union

Entity Tier 4

This tier is a collection of other entities, wherever this tier is referenced, the following entities are allowed:

Event

Alias

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'alias'	REQUIRED.
items	Entity Tier 3	REQUIRED.

Example

{
  "kind": "alias",
  "items": {
    "kind": "union",
    "items": [{ "type": "string" }, { "type": "number" }]
  }
}

Enum

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'enum'	REQUIRED.
entries	Object<string, Literal>	REQUIRED. An object.

Example

{
  "kind": "enum",
  "entries": {
    "CODE": {
      "kind": "literal",
      "value": 2
    }
  }
}

Literal

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'literal'	REQUIRED.
value	number | boolean | string	REQUIRED.

Example

{
  "kind": "literal",
  "value": 13
}

Module

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'module'	REQUIRED.
entries	Object<string, Entity Tier 1 | Entity Tier 2 | Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 1 | Entity Tier 2 | Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "module",
  "entries": {
    "a": { /* entity */ },
    "b": { /* entity */ }
  }
}

Object

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'object'	REQUIRED.
extends	Array<Entity Base>	References to other entities this entity extends from.
implements	Array<Entity Base>	References to other entities this entity implements.
entries	Object<string, Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "object",
  "entries": {
    "prop": { /* entity */ }
  }
}

Namespace

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'namespace'	REQUIRED.
entries	Object<string, Entity Tier 1 | Entity Tier 2 | Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 1 | Entity Tier 2 | Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "namespace",
  "entries": {
    "subspace": { /* entity */ }
  }
}

Function

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'function'	REQUIRED.
params	Array<Entity Tier 3>	REQUIRED. The parameters for this entity.
returns	Entity Tier 3	The return type from this entity.
this	Entity Tier 3	The value of this.
async	boolean	Indicates whether this function is asynchronous.
yields	Array<Entity Tier 3>	The entities this function yields.
emits	Array<Entity Base>	The events this entity emits.
throws	Array<Entity Base>	The errors this entity throws.
entries	Object<string, Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "function",
  "params": [{
    "name": "first"
    "type": "string",
    "optional": true,
    "variable": true
  }],
  "returns": {
    "type": "Promise<number>"
  },
  "async": true
}

Class

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'class'	REQUIRED.
extends	Array<Entity Base>	References to other entities this entity extends from.
implements	Array<Entity Base>	References to other entities this entity implements.
constructor	Constructor Object
staticEntries	Object<string, Entity Tier 3>	An object.
entries	Object<string, Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 2 | Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "class",
  "constructor": {
    "params": []
  },
  "staticEntries": {
    "fun": { /* entity */ }
  }
}

Constructor Object

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'function'	REQUIRED.
params	Array<Entity Tier 3>	The parameters for this entity.

Interface

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'interface'	REQUIRED.
params	Array<Entity Tier 3>	The parameters for this entity.
returns	Entity Tier 3	The return type from this entity.
this	Entity Tier 3	The value of this.
extends	Array<Entity Base>	References to other entities this entity extends from.
implements	Array<Entity Base>	References to other entities this entity implements.
entries	Object<string, Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 2 | Entity Tier 3>	An object.
events	Object<string, Event>	An object.

Example

{
  "kind": "interface",
  "entries": {
    "a": { /* entity */ }
  }
}

Event

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'event'	REQUIRED.
params	Array<Entity Tier 3>	The parameters for this entity.
returns	Entity Tier 3	The return type from this entity.
this	Entity Tier 3	The value of this.
entries	Object<string, Entity Tier 3>	An object.
definitions	Object<string, Entity Tier 3>	An object.

Example

{
  "kind": "event",
  "params": []
}

Array

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'array'	REQUIRED.
items	Array<Entity Tier 3> | Entity Tier 3
definitions	Object<string, Entity Tier 3>	An object.

Example

{
  "kind": "array",
  "items": { /* entity */ } // all values in array are of same type
}

{
  "kind": "array",
  "items": [ {/* entity */ }, { /* entity */ }] // tuple
}

Union

This entity extends from Entity Base and accepts all its fields as well.

Field	Type	Description
kind	const 'union'	REQUIRED.
items	Array<Entity Tier 3>
definitions	Object<string, Entity Tier 3>	An object.

Example

{
  "kind": "union",
  "items": [{ /* entity */ }, { /* entity */ }]
}