OpenPkg Specification

Abstract

The OpenPkg Specification defines a standard, language-service-independent interface description for TypeScript packages. An OpenPkg document describes the complete public surface of a package (its functions, classes, interfaces, type aliases, enums, and variables) as JSON Schema, allowing both humans and machines to discover and understand the capabilities of a package without access to its source code, its node_modules, or a TypeScript compiler.

An OpenPkg document can then be used by documentation generators to display the API, code-generation tools to consume it, diff tools to detect breaking changes between versions, and agents to reason about a package's capabilities.

Status of This Document

This is a draft of the 0.4.0 line of the specification. It is published for implementers and is subject to change. The canonical JSON Schema for validation is published with each release of @openpkg-ts/spec. Earlier document versions 0.2.0 and 0.3.0 remain valid; see § 9 Versioning.

1.Introduction

TypeScript's type system is the richest description of a JavaScript package's behavior, but that description is locked inside the compiler: consuming it requires source files, dependency installation, and a type checker. The OpenPkg Specification extracts that description into a single portable JSON document, in the same way the OpenAPI Specification extracts the description of an HTTP service out of its implementation.

A conforming document is self-contained. Every named type referenced by an exported symbol is either inlined as a schema or declared in the document's types section and referenced by a JSON Reference. Consumers never need to resolve anything outside the document.

2.Notational Conventions

The key words must, must not, required, shall, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].

Fields marked required in the tables below must be present. All other fields are optional. Producers must not emit fields whose value is undefined; omission and undefined are equivalent.

3.Format and Media Type

An OpenPkg document is a single JSON object encoded in UTF-8. The conventional filename is openpkg.json. Schema values within the document are expressed in a constrained profile of JSON Schema draft 2020-12 [JSON-SCHEMA], extended with the vendor fields defined in § 5.6.

A document may declare the meta-schema it validates against via the $schema field:

{ "$schema": "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json" }

4.Document Structure

The root of every OpenPkg document is the OpenPkg Object.

5.Object Definitions

5.1Meta Object

5.2Export Object

Describes one exported symbol. The kind field determines which of the remaining fields are meaningful: callable kinds carry signatures, structural kinds carry members, and value kinds carry schema.

5.3Signature Object

5.4Member Object

Describes one member of a class, interface, or enum. Fields mirror the Export Object where meaningful: name, kind, description, schema, signatures, tags, deprecated. Two fields are member-specific:

visibility

"public" · "protected" · "private". Producers should omit private members unless explicitly configured otherwise.

flags

Modifier map (e.g. static, readonly, abstract, async, optional).

Members inherited from a base class are listed with an inheritedFrom field naming the ancestor, so consumers can render flattened or hierarchical views without re-walking the inheritance chain.

5.5Type Object

A named type declared in the document's types section. Type Objects are the targets of #/types/… references and use the same field vocabulary as Export Objects (id, name, kind, schema, members, source, extends, implements). Its kind is one of "class" · "interface" · "type" · "enum" · "external". Types resolved from a package's dependencies carry external: true together with a Source Object naming the providing package.

5.6Schema Object

Type shapes are expressed as JSON Schema draft 2020-12 vocabulary: type, properties, required, items, enum, additionalProperties, anyOf, allOf, oneOf, and $ref. TypeScript constructs with no JSON Schema equivalent are preserved through the following vendor extensions, which consumers may ignore without losing structural validity:

Unions of literals collapse to enum. Optional properties are expressed by omission from required, never by | undefined in the schema. Tuples use items with minItems/maxItems. Index signatures map to additionalProperties.

5.7Source Object

5.8Generation Object

Optional provenance for the document: generator (tool name and version), timestamp (ISO 8601), mode ("source" or "declaration-only"), known limitations of declaration-only extraction, and a skipped list naming exports the producer omitted and why ("filtered" · "no-declaration" · "internal" · "external-unresolved"). Consumers must not treat generation metadata as part of the described API.

6.Type References

A schema referencing a named type uses a JSON Reference whose target is the document's own types section:

{ "$ref": "#/types/ExtractOptions" }

The fragment must take the form #/types/{id}, where {id} matches the id of exactly one Type Object. Producers must emit a Type Object for every reference target (no dangling references) and must not reference targets outside the document. Generic instantiations attach x-ts-type-arguments beside the $ref rather than minting new type entries per instantiation.

7.Specification Extensions

Two extension surfaces exist. Schema-level extensions are the x- prefixed fields of § 5.6. Document-level extensions live under the root extensions object, which is an open map; the single field defined by this specification is presentation, a map from export id to display metadata (slug, displayName, category, importPath, alias) for documentation front ends. Unknown extension fields must be preserved by tools that rewrite documents.

8.Complete Example

A minimal, conforming document describing a package with one function and one referenced interface:

{
  "$schema": "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json",
  "openpkg": "0.4.0",
  "meta": {
    "name": "greeter",
    "version": "1.0.0",
    "ecosystem": "js/ts"
  },
  "exports": [
    {
      "id": "greet",
      "name": "greet",
      "kind": "function",
      "description": "Render a greeting for a person.",
      "signatures": [
        {
          "parameters": [
            { "name": "person", "required": true,
              "schema": { "$ref": "#/types/Person" } }
          ],
          "returns": { "schema": { "type": "string" } }
        }
      ],
      "source": { "file": "src/index.ts", "line": 12 }
    }
  ],
  "types": [
    {
      "id": "Person",
      "name": "Person",
      "kind": "interface",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "number" }
        },
        "required": ["name"]
      },
      "source": { "file": "src/index.ts", "line": 4 }
    }
  ]
}

9.Versioning and Conformance

The specification is versioned by the root openpkg field. Recognized versions are 0.2.0, 0.3.0, and 0.4.0; each publishes its own JSON Schema. Within the 0.x line, minor versions may add fields but must not change the meaning of existing ones.

A document is conforming when it validates against the JSON Schema of its declared version and satisfies the prose constraints of this document (no dangling references, no undefined members in required, unique id values). A consumer is conforming when it accepts every conforming document of the versions it claims to support and ignores unrecognized x- fields rather than rejecting them.

Appendix A. Export Kinds

Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997.

[JSON-SCHEMA]

"JSON Schema: A Media Type for Describing JSON Documents", draft 2020-12.

[RFC8259]

Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.