Documentation
¶
Overview ¶
Package schema declares the optional type schema for a labelled property graph: which labels exist, which property keys exist, which lpg.PropertyKind each property carries, and which properties each label requires.
A *Schema is a runtime enforcement hook, not merely advisory. Install one on a graph with github.com/FlavioCFOliveira/GoGraph/graph/lpg.Graph.SetValidator and the two declared invariants are enforced on the write path:
- Per-property typing — Schema.Validate runs inside every SetNodeProperty / SetEdgeProperty call, rejecting a value whose kind disagrees with its declaration before the write is applied.
- Required-property existence — Schema.ValidateNode runs when a node is finalised, via lpg.Graph.ValidateNode, rejecting a node that is missing a property its label requires (see Schema.RequireProperty).
The split is deliberate: typing is decided from a single value at the mutation point, but existence can only be decided once a node is complete (a node acquires its label before the property that label requires), so existence is enforced at the finalisation boundary rather than mid-build.
Callers may also run Schema.Validate and Schema.ValidateNode directly, before applying a write, to reject incompatible data early. The schema is also the surface the persistence layer serialises alongside snapshots so opens can reject incompatible data.
Index ¶
- Variables
- type Schema
- func (s *Schema) LabelRegistry() *lpg.LabelRegistry
- func (s *Schema) Labels() []string
- func (s *Schema) Properties() map[string]lpg.PropertyKind
- func (s *Schema) PropertyKeyRegistry() *lpg.PropertyKeyRegistry
- func (s *Schema) PropertyKind(name string) (lpg.PropertyKind, bool)
- func (s *Schema) RegisterLabel(name string) lpg.LabelID
- func (s *Schema) RegisterProperty(name string, kind lpg.PropertyKind) (lpg.PropertyKeyID, error)
- func (s *Schema) RequireProperty(labelName, propertyName string)
- func (s *Schema) Validate(propertyName string, value lpg.PropertyValue) error
- func (s *Schema) ValidateNode(labels []string, props map[string]lpg.PropertyValue) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMissingRequired = errors.New("schema: missing required property")
ErrMissingRequired is returned by Schema.ValidateNode when a node is missing a property that its label requires.
var ErrTypeMismatch = errors.New("schema: property type mismatch")
ErrTypeMismatch is returned by Schema.Validate when a value's kind does not match the kind declared for its property key.
var ErrUnknownProperty = errors.New("schema: unknown property key")
ErrUnknownProperty is returned by Schema.Validate when a value is supplied for a property key that has not been registered.
Functions ¶
This section is empty.
Types ¶
type Schema ¶
type Schema struct {
// contains filtered or unexported fields
}
Schema is the registry of declared labels and property kinds. It is safe for concurrent use.
Example ¶
ExampleSchema declares property typing and a per-label requirement, then validates candidate nodes against the declaration. Validation is opt-in: callers run it before applying a write to reject incompatible data early.
package main
import (
"errors"
"fmt"
"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
"github.com/FlavioCFOliveira/GoGraph/graph/lpg/schema"
)
func main() {
s := schema.New(lpg.NewLabelRegistry(), lpg.NewPropertyKeyRegistry())
// Declare that "Person" exists and that "age" is an Int64 property
// every Person must carry.
s.RegisterLabel("Person")
_, _ = s.RegisterProperty("age", lpg.PropInt64)
s.RequireProperty("Person", "age")
// A Person with a correctly typed age satisfies the schema.
ok := s.ValidateNode(
[]string{"Person"},
map[string]lpg.PropertyValue{"age": lpg.Int64Value(30)},
)
// A Person missing the required "age" fails with ErrMissingRequired.
missing := s.ValidateNode([]string{"Person"}, map[string]lpg.PropertyValue{})
fmt.Println("valid node:", ok)
fmt.Println("missing required:", errors.Is(missing, schema.ErrMissingRequired))
}
Output: valid node: <nil> missing required: true
func New ¶
func New(labels *lpg.LabelRegistry, properties *lpg.PropertyKeyRegistry) *Schema
New returns an empty schema. The supplied label and property-key registries are reused — typically those owned by the lpg.Graph the schema describes — so identifiers stay consistent across the schema and the live graph.
func (*Schema) LabelRegistry ¶
func (s *Schema) LabelRegistry() *lpg.LabelRegistry
LabelRegistry returns the underlying label registry. The schema and the registry share state; mutations on the registry leak out of the schema's validation surface but the IDs stay consistent.
func (*Schema) Properties ¶
func (s *Schema) Properties() map[string]lpg.PropertyKind
Properties returns a snapshot of declared (name, kind) pairs.
func (*Schema) PropertyKeyRegistry ¶
func (s *Schema) PropertyKeyRegistry() *lpg.PropertyKeyRegistry
PropertyKeyRegistry returns the underlying property-key registry.
func (*Schema) PropertyKind ¶
func (s *Schema) PropertyKind(name string) (lpg.PropertyKind, bool)
PropertyKind returns the kind declared for name and true, or 0 and false when name has not been registered.
func (*Schema) RegisterLabel ¶
RegisterLabel records name as a declared label and returns its stable lpg.LabelID. Idempotent.
func (*Schema) RegisterProperty ¶
func (s *Schema) RegisterProperty(name string, kind lpg.PropertyKind) (lpg.PropertyKeyID, error)
RegisterProperty records name as a property key carrying the given kind, returning the stable lpg.PropertyKeyID. Registering the same name twice with different kinds is rejected with an error.
func (*Schema) RequireProperty ¶
RequireProperty records that any node carrying labelName must have propertyName set. The call is idempotent: repeating the same (label, property) pair has no effect. The label and property do not need to be pre-registered — the requirement is stored regardless and evaluated by Schema.ValidateNode.
When the schema is installed on a graph via github.com/FlavioCFOliveira/GoGraph/graph/lpg.Graph.SetValidator, the requirement is enforced — not merely advisory — at the node-finalisation boundary through lpg.Graph.ValidateNode: a finalised node missing the required property is rejected with ErrMissingRequired.
func (*Schema) Validate ¶
func (s *Schema) Validate(propertyName string, value lpg.PropertyValue) error
Validate checks value against the declared kind for the named property. Returns nil on a match, ErrUnknownProperty when the property is unregistered, or ErrTypeMismatch when the value's kind disagrees with the declaration.
Example ¶
ExampleSchema_Validate checks a single value against the declared kind of its property key, reporting ErrTypeMismatch when the kinds disagree and ErrUnknownProperty when the key was never registered.
package main
import (
"errors"
"fmt"
"github.com/FlavioCFOliveira/GoGraph/graph/lpg"
"github.com/FlavioCFOliveira/GoGraph/graph/lpg/schema"
)
func main() {
s := schema.New(lpg.NewLabelRegistry(), lpg.NewPropertyKeyRegistry())
_, _ = s.RegisterProperty("age", lpg.PropInt64)
good := s.Validate("age", lpg.Int64Value(42))
wrongType := s.Validate("age", lpg.StringValue("not a number"))
unknown := s.Validate("nickname", lpg.StringValue("ace"))
fmt.Println("int64 ok:", good)
fmt.Println("type mismatch:", errors.Is(wrongType, schema.ErrTypeMismatch))
fmt.Println("unknown key:", errors.Is(unknown, schema.ErrUnknownProperty))
}
Output: int64 ok: <nil> type mismatch: true unknown key: true
func (*Schema) ValidateNode ¶
ValidateNode checks that a node described by labels and props satisfies every requirement recorded in the schema:
- Every property name declared as required for any of the node's labels is present in props.
- Every property present in props whose name has been registered carries a value of the declared kind.
The first violation encountered is returned. On success, nil is returned.
Source Files