Skip to content

schema-metadata.md

Latest commit

 

History

History
163 lines (125 loc) · 4.03 KB

schema-metadata.md

File metadata and controls

163 lines (125 loc) · 4.03 KB
title Schema Metadata
sidebar_position 35
id schema_metadata
license Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

JavaScript schema metadata is declared with Type.* builders or TypeScript decorators. Metadata defines type identity, field types, nullability, reference tracking, dynamic fields, and per-struct schema evolution behavior.

Type Identity

Structs and enums can use a numeric ID or a namespace/name pair. Pick one identity strategy for a type and use it consistently in every runtime that reads or writes the payload.

import { Type } from "@apache-fory/core";

const byId = Type.struct(
  { typeId: 1001 },
  {
    id: Type.int64(),
    name: Type.string(),
  },
);

const byName = Type.struct(
  { namespace: "example", typeName: "user" },
  {
    id: Type.int64(),
    name: Type.string(),
  },
);

Decorator Metadata

Decorators keep the schema next to a TypeScript class declaration:

@Type.struct({ typeName: "example.user" })
class User {
  @Type.int64()
  id!: bigint;

  @Type.string()
  name!: string;
}

The decorator metadata is equivalent to the builder metadata registered with fory.register(...).

Field Types

Use explicit scalar builders for stable contracts:

Type.int8();
Type.int16();
Type.int32();
Type.int64(); // JavaScript value is bigint
Type.uint32();
Type.uint64(); // JavaScript value is bigint
Type.float16();
Type.bfloat16();
Type.float32();
Type.float64();
Type.string();
Type.binary();

Use collection builders for nested values:

Type.list(Type.string());
Type.map(Type.string(), Type.int32());
Type.set(Type.string());
Type.int32Array();
Type.float64Array();

Nullability

Fields are non-nullable unless the schema says otherwise:

const userType = Type.struct("example.user", {
  name: Type.string(),
  email: Type.string().setNullable(true),
});

Passing null to a non-nullable field throws.

Reference Tracking

When the same object instance can appear in multiple fields, or when an object graph can be circular, enable global reference tracking and mark reference-tracked fields:

import Fory, { Type } from "@apache-fory/core";

const fory = new Fory({ ref: true });

const nodeType = Type.struct("example.node", {
  next: Type.struct("example.node").setNullable(true).setTrackingRef(true),
});

Field-level reference metadata has no effect unless new Fory({ ref: true }) is also set.

Dynamic Fields

Use Type.any() when a field can hold different Fory values at runtime:

const eventType = Type.struct("example.event", {
  kind: Type.string(),
  payload: Type.any(),
});

For a struct field with a declared type, .setDynamic(Dynamic.FALSE) always treats values as the declared type and .setDynamic(Dynamic.TRUE) always writes the runtime type. The default Dynamic.AUTO is appropriate for most fields.

Per-Struct Schema Evolution

JavaScript uses compatible schema evolution by default. For a stable struct that should omit evolution metadata, set evolving: false:

const fixedType = Type.struct(
  { typeId: 1002, evolving: false },
  {
    name: Type.string(),
  },
);

Both writer and reader must agree on evolving: false.

Related Topics