Skip to main content

@palantir/pack.schema

TypeScript builders for defining versioned document schemas for PACK. You author a schema as a chain of versions; the SDK generator turns it into typed, per-version read and write APIs for your application.

Records and unions​

Field types come from the primitives on the namespace — String, Double, Boolean, Optional, Array — or a reference to another record or union. Reference a model by passing it directly, or as () => Model for forward and circular references.

Versions​

A schema is a chain of versions:

  • defineSchema — version 1, the initial set of models.
  • defineSchemaUpdate — a named change that evolves records through a builder.
  • nextSchema — compose one or more updates into the next version.

Export the latest version as the module's default export; the generator walks the chain back to the minimum supported version.

Example​

import * as S from "@palantir/pack.schema";

// v1: the initial schema.
const ShapeBox = S.defineRecord("ShapeBox", {
  docs: "A box.",
  fields: {
    top: S.Double,
    left: S.Double,
    color: S.Optional(S.String),
  },
});

const schemaV1 = S.defineSchema({ ShapeBox });

// v2: split `color` into separate fill and stroke colors. `derivedFrom`
// back-fills the new fields when reading v1 documents.
const splitColor = S.defineSchemaUpdate(
  "splitShapeColorIntoFillAndStroke",
  schema => {
    const ShapeBox = schema.ShapeBox
      .addField("fillColor", S.Optional(S.String), { derivedFrom: ["color"] })
      .addField("strokeColor", S.Optional(S.String), { derivedFrom: ["color"] })
      .deprecateField("color", "Use fillColor and strokeColor instead.")
      .build();
    return { ShapeBox };
  },
);

const schemaV2 = S.nextSchema(schemaV1).addSchemaUpdate(splitColor).build();

// The default export is the latest version.
export default schemaV2;