Resource state model.

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

• Resource — Complete resource state (HTTP GET/PUT)
• Patch — Partial resource updates (HTTP PATCH)
• Values — Property value sets
• Value — Individual property values
• IRI — Resource identifiers
• Literal — Primitive data values
• Dictionary — Localized text values

Resource Operations

Retrieving

A Resource is a property 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 property mapped to @id in the application-defined JSON-LD @context, identifying the resource globally. This property is usually named id, but the mapping is arbitrary. A state without such a property 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

Patching

A Patch serves as payload for HTTP PATCH operations. Properties can be set to new values or deleted using null; unlisted properties remain unchanged:

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

({
  "price": 39.99,         // update
  "description": null,    // delete
  "available": true,      // update
  "categories": []        // delete
})
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 property in a resource state or patch holds Values:

• a single Value
• a Dictionary of localized textual values
• an array representing a set of values

A Value can be:

• Literal: primitive data (boolean, number, string)
• IRI: web identifier referencing a resource
• nested state: embedded resource description (object with property values)

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

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

Localized Text

For multilingual content, use a Dictionary — an object mapping language tags to localized strings. Language tags follow RFC 5646 (e.g., 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

A dictionary must be either single-valued (one string per tag) or multi-valued (string arrays per tag) throughout; mixing cardinalities within the same dictionary is not supported.