Module resource

Resource shape model and factories.

Provides shapes for validating linked data resources with property definitions, cardinality constraints, and inheritance. Resource shapes define the expected structure of linked data resources using a SHACL-based model with compile-time type inference.

Defining Resource Shapes

Combine property definitions with value ranges to define resource structures:

import { resource, id, required, optional, repeatable } from '@metreeca/blue';
import { string, integer, boolean, reference } from '@metreeca/blue';

const Product = resource({
  id: id(),
  name: required(string({ minLength: 1 })),
  price: required(integer({ minInclusive: 0 })),
  available: optional(boolean()),
  tags: repeatable(string())
});
Copy

Properties and Ranges

Ranges define cardinality constraints for property values:

import { resource, property, required, optional, multiple, repeatable, cardinality } from '@metreeca/blue';
import { string } from '@metreeca/blue';

const Shape = resource({
  name: required(string()),           // 1..1
  alias: optional(string()),          // 0..1
  tags: repeatable(string()),         // 1..*
  notes: multiple(string()),          // 0..*
  codes: cardinality(2, 5)(string())  // 2..5
});
Copy

Naked ranges are automatically wrapped in a property; use explicit property when IRI mappings or labels are needed:

import { resource, property, required, string } from '@metreeca/blue';
import { createNamespace } from '@metreeca/core/resource';

const schema = createNamespace("http://schema.org/");

const Person = resource({
  name: property({ forward: schema }, required(string()))
});
Copy

Resource References and Embedding

Resource properties link to other resources in two ways. A reference wrapper links to a standalone resource — an independently identified and managed entity. A direct shape inclusion defines an embedded resource — a nested object with no independent identity, created and managed together with its parent.

import { resource, id, required, optional, reference } from '@metreeca/blue';
import { string, number } from '@metreeca/blue';

const Rating = resource({
  average: required(number({ minInclusive: 0, maxInclusive: 5 })),
  reviews: required(number({ minInclusive: 0 }))
});

const Vendor = resource({
  id: id(),
  name: required(string())
});

const Product = resource({
  id: id(),
  name: required(string()),
  rating: optional(Rating),            // embedded
  vendor: required(reference(Vendor)) // standalone
});
Copy

Use backlink for reverse links managed by the target resource. Backlinks are read-only from the source resource perspective: included in responses but rejected in state updates and patches.

Self-referential shapes use lazy factories:

function Category() {
  return resource({
    id: id(),
    name: required(string()),
    parent: optional(reference(Category))
  });
}
Copy

Inheritance

Extend parent shapes to inherit properties and constraints:

import { resource, id, required, string, integer, reference } from '@metreeca/blue';

const NamedEntity = resource({
  id: id(),
  name: required(string({ minLength: 1 }))
});

const Employee = resource({

  extends: NamedEntity

 }, {
  department: required(string()),
  salary: required(integer({ minInclusive: 0 }))
});
Copy

Polymorphic Properties

Use union for properties accepting multiple value types. Unions are pure type discriminators — cardinality constraints belong on the enclosing Range, not on individual variants. At runtime, union values are represented as Indexed records mapping variant names to their values, corresponding to JSON-LD indexed containers (@container: @index):

import { resource, property, union, optional, reference, string } from '@metreeca/blue';

const PostalAddress = resource({
  street: required(string()),
  city: required(string())
});

const Contact = resource({
  address: optional(union({
    text: string(),
    PostalAddress: reference(PostalAddress)
  }))
});
Copy

Variant keys act as discriminators in runtime values:

{
  "address": {
    "text": "123 Main St"
  }
}

{
  "address": {
    "PostalAddress": {
      "id": "https://data.example.com/addresses/456",
      "streetAddress": "12 Harbour Street",
      "addressLocality": "Copenhagen"
    }
  }
}
Copy