Documentation
¶
Overview ¶
Package json provides JSON encoding and decoding for the operation graph.
Index ¶
Constants ¶
const ( Decode op.ActionName = "json.decode" Encode op.ActionName = "json.encode" EncodeIndent op.ActionName = "json.encode_indent" Parse op.ActionName = "json.parse" )
Action-name constants for the json provider's plan-mode actions.
Each constant is the short dotted action label its method dispatches under. Pass these to plan.Plan, op.ReceiverRegistry().BuildAction, RuntimeEnvironment.ActionByName, or WithActionNamed in place of a string literal so a typo is a compile error and rename / find-references work through the constant.
const SchemeJSON = "json"
SchemeJSON is the URI scheme for JSON resources.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Provider ¶
type Provider struct {
op.ProviderBase
}
Provider provides JSON encoding and decoding operations.
func NewProvider ¶
func NewProvider(runtimeEnvironment *op.RuntimeEnvironment) *Provider
NewProvider creates a JSON provider bound to the given context.
func (*Provider) Decode ¶
Decode parses a JSON string into a Go value.
Parameters:
- `data`: the JSON text to parse.
Returns:
- `any`: the decoded Go value (maps, slices, and scalars per encoding/json).
- `error`: non-nil when `data` is not valid JSON.
+devlore:claim=deterministic
func (*Provider) Encode ¶
Encode marshals a Go value to a compact JSON string.
Parameters:
- `value`: the Go value to marshal.
Returns:
- `string`: the compact JSON encoding of `value`.
- `error`: non-nil when `value` cannot be marshaled to JSON.
+devlore:claim=deterministic
func (*Provider) EncodeIndent ¶
EncodeIndent marshals a Go value to an indented JSON string.
Parameters:
- `value`: the Go value to marshal.
- `indent`: the per-level indentation string (e.g., " " or "\t").
Returns:
- `string`: the indented JSON encoding of `value`.
- `error`: non-nil when `value` cannot be marshaled to JSON.
+devlore:claim=deterministic
func (*Provider) Parse ¶
Parse decodes a JSON string into a Resource that holds the parsed Go value.
Unlike Decode, which returns a bare Go value (marshaled to a Starlark dict), Parse returns a Resource whose internal representation can be validated against a JSON Schema or re-encoded without Starlark↔Go round-trips.
Parse is content-keyed — two calls with the same input produce the same URI and share a single canonical catalog entry. The first caller's `Unit.ID()` stamps producerID; subsequent same-content callers get the existing entry unchanged. NewResource handles the parse, hash, and catalog interning in one step.
Parameters:
- `activationRecord`: the per-dispatch activation; its `Unit` stamps the produced Resource's producerID.
- `data`: the JSON text to parse.
Returns:
- `Resource`: the canonical catalog entry holding the parsed value.
- `error`: non-nil when `data` is not valid JSON or catalog interning fails.
+devlore:claim=deterministic
type Resource ¶
type Resource interface {
op.Resource
// Data returns the canonical JSON bytes. Content-addressed: the digest derives from them.
Data() []byte
// Hash returns the hex-encoded digest of [Resource.Data].
Hash() string
// Parsed returns the decoded Go value — map[string]any, []any, or a scalar.
Parsed() any
// contains filtered or unexported methods
}
Resource represents a parsed JSON document held in memory, identified by the SHA-256 of its canonical form.
Unlike [mem.Resource] which holds opaque bytes, json.Resource carries a parsed Go value (map[string]any, []any, scalars) that can be validated against a JSON Schema or re-encoded without Starlark↔Go round trips.
Identity is content-addressed via canonicalization: the input bytes are parsed with encoding/json and re-marshaled to produce a canonical byte form (map keys sorted, no whitespace, stable scalar serialization). The SHA-256 of those canonical bytes drives the URI-specific (`json:<hex>`) and the Hash field. Two semantically equal inputs — `{"a":1,"b":2}` and `{"b":2,"a":1}` — produce identical URIs by construction.
Canonicalization Warnings:
- Not RFC 8785 (JCS) compliant. Within-Go determinism only; cross-language portability not in scope.
- Numbers larger than 2^53 lose precision via `float64` round trip — two distinct large integers can collide.
- Object key sort is UTF-8 byte order (Go's encoding/json default), not the UTF-16 order JCS specifies. Agrees with JCS for ASCII keys; diverges for the supplementary plane.
Resource is this provider's resource type — the sealed interface over a canonicalized JSON document.
Sealed by an unexported marker, so the closed set of implementations is the one this package declares. A value reaching a json method therefore came from a constructor and carries catalog-issued identity; nothing hand-built or reflectively hydrated can satisfy it.
func DiscoverResource ¶
func DiscoverResource(runtimeEnvironment *op.RuntimeEnvironment, value any) (Resource, error)
DiscoverResource constructs a json.Resource and registers it without claiming production.
Used by the framework's resource registry adapter for slot coercion (when starlark supplies a string and the slot expects a *json.Resource) and by callers holding a reference handle without claiming production. UnmarshalJSON / UnmarshalText / UnmarshalYAML rehydration is the canonical use case.
Discover does not stamp a producer, so unlike NewResource it takes only `runtimeEnvironment` — no unit reference is needed.
Same value-shape dispatch as NewResource: raw JSON bytes, an io.Reader, or a canonical tag URI string.
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `value`: raw JSON bytes ([]byte), an io.Reader, or a canonical tag URI string; same dispatch as NewResource.
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported value type, JSON parse failure, malformed URI, or identity construction failure.
func NewResource ¶
func NewResource(runtimeEnvironment *op.RuntimeEnvironment, producerID string, value any) (Resource, error)
NewResource constructs a json.Resource and claims production via op.ResourceCatalog.GetOrCreate.
The json.Resource is content-keyed — the URI is `json:<sha256-hex>` derived from the canonical form of the input, so two callers with semantically equal inputs produce the same URI and share a single catalog entry. The first caller's `Unit.ID()` stamps producerID; later calls for the same content get the existing entry unchanged.
Use NewResource from a producer dispatch context. Use DiscoverResource instead when the caller is not claiming production (rehydration, the framework's slot-coercion adapter).
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `producerID`: the producing caller's id (`activationRecord.CallerID`), or "" for caller-less dispatch. for non-graph dispatch.
- `value`: raw JSON bytes ([]byte), an io.Reader streaming JSON, or a canonical tag URI string. Bytes and streams are parsed and canonicalized during construction; an invalid JSON document errors here.
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported value type, JSON parse failure, malformed URI, or identity construction failure.
type ValidationResult ¶
type ValidationResult struct {
// Valid is true when the document conforms to the schema.
Valid bool `json:"valid" starlark:"valid"`
// Errors is the list of validation error messages; empty when Valid is true.
Errors []string `json:"errors" starlark:"errors"`
}
ValidationResult holds the outcome of a JSON Schema validation.
Source Files
Directories