Resource state representation.

Defines types for describing resource states and partial updates in REST/JSON APIs, using native JSON types with localised text support.

Data model

• Resource — Complete resource state (HTTP GET/PUT)
• Values — Property value sets
• Value — Individual property values
• Dictionary — Localised text map (single- or multi-valued per tag)
• Literal — Primitive scalar value (boolean, number, string)
• Reference — Absolute IRI identifying a linked resource

Type guards

• isResource — checks if a value is a Resource
• isValues — checks if a value is a Values set
• isValue — checks if a value is a Value
• isDictionary — checks if a value is a Dictionary
• isLiteral — checks if a value is a Literal
• isReference — checks if a value is a Reference
• isVacuous — checks if a value is vacuous, carrying no content

Codecs

• encodeResource — encodes a Resource as JSON
• decodeResource — decodes a Resource from JSON

Resource Operations

Retrieving

A Resource is a field map describing the state of a resource:

GET https://example.com/products/42
Copy

{
  "id": "/products/42",
  "name": "Widget",
  "price": 29.99,
  "available": true
}
Copy

Resources may include an IRI field mapped to @id in the application-defined JSON-LD @context, identifying the resource globally. This field is usually named id, but the mapping is arbitrary. A state without such a field represents an anonymous (blank) node, useful for nested structures that don't need their own identity:

{
  "id": "/products/42",
  "name": "Widget",
  "price": 29.99,
  "dimensions": {
    "width": 10,
    "height": 5,
    "depth": 3
  }
}
Copy

Resources can link to other resources using IRI references or embedded descriptions. IRI references identify a resource without describing its state, while embedded descriptions include the linked resource's properties:

// IRI references: compact form linking to external resources

({
  "id": "/products/42",
  "name": "Widget",
  "price": 29.99,
  "vendor": "/vendors/acme",
  "categories": ["/categories/electronics", "/categories/home"]
})

// Embedded descriptions: expanded form with linked resource properties

({
  "id": "/products/42",
  "name": "Widget",
  "price": 29.99,
  "vendor": {
    "id": "/vendors/acme",
    "name": "Acme Corp"
  },
  "categories": [
    { "id": "/categories/electronics", "name": "Electronics" },
    { "id": "/categories/home", "name": "Home" }
  ]
})
Copy

Creating

A Resource serves as payload for HTTP POST operations:

POST https://example.com/products/
Copy

{
  "name": "Gadget",
  "price": 49.99,
  "categories": ["electronics", "home"],
  "available": true
}
Copy

// Using IRI references (always valid)

({
  "name": "Gadget",
  "price": 49.99,
  "vendor": "/vendors/acme"
})

// Using nested states with only the identifier property (always valid)

({
  "name": "Gadget",
  "price": 49.99,
  "vendor": {
    "id": "/vendors/acme"
  }
})

// Using nested states with additional properties (must be declared as embedded)

({
  "name": "Gadget",
  "price": 49.99,
  "vendor": {         // requires 'vendor' declared as embedded
    "id": "/vendors/acme",
    "name": "Acme Corp"
  }
})
Copy

Updating

A Resource also serves as payload for HTTP PUT operations:

PUT https://example.com/products/42
Copy

({
  "name": "Widget",
  "price": 79.99,
  "categories": ["electronics", "premium"]
  // available       // not included → deleted
})
Copy

Deleting

HTTP DELETE operations remove the resource at the request URL (no payload is required):

DELETE https://example.com/products/42
Copy

Value Types

Each field in a resource state holds a value set: a single scalar, a Dictionary of localised text, or an array of scalars.

A Value is a single scalar:

• Literal — primitive data (boolean, number, string)
• Reference — absolute IRI identifying a linked resource
• Resource — nested resource state

A Values set extends Value with collection forms:

• a Dictionary of localised text
• an array of Value elements, with mixed element types permitted

The same holds for any vacuous value carrying no content: {}, [], an empty dictionary, or a structure holding only vacuous values, such as { "address": {} } or [{}]. A field holding a vacuous value is treated as omitted.

IRIs

An IRI (Internationalized Resource Identifier) is a globally unique string identifying a resource on the web. IRIs enable entity linking by referencing resources without embedding their full state. Properties mapped to @id in the application-provided JSON-LD @context expect IRI values, establishing relationships between resources across systems and domains.

Literals

Primitive values (boolean, number, string) map directly to JSON primitives. Dates, times, and other structured values are represented as strings in standard formats (for example, ISO 8601). Application-level @context objects can declare datatype coercion rules for JSON-LD processing.

Dictionaries

For multilingual content, use a Dictionary. Language tags follow RFC 5646 (for example, en, de-CH, zh-Hans):

// single value per language

({
  "en": "Universal Widget",
  "fr": "Widget Universel",
  "de": "Universelles Widget"
})

// multiple values per language

({
  "en": ["tool", "gadget", "utility"],
  "fr": ["outil", "gadget"]
})
Copy

Within a single dictionary, all values MUST be uniformly scalar or uniformly array, and the form chosen MUST be the one the property declares: a payload carrying an array under a tag for a property holding one string per tag, or the converse, is malformed and rejected by servers.