Resource Registry Service Logo
6.0.0-SNAPSHOT
  • Introduction to Information Systems
    • What is an Information System for a Federated Research Infrastructure?
    • The System of Systems (SoS) Paradigm
    • The Necessity of a Data Definition Language (DDL)
    • The Open-World Extensibility Paradigm
  • Normative Terminology & Typographic Conventions
    • How to Refer to the Information System Model
    • Typographic & Foundational Conventions
    • Manifestation vs Projection (Data vs Topology)
    • Topological Verbs & Sentence Patterns (Entity vs Graph Edge Abstraction)
      • 1. Patterns for “attached” (Composition: Resource – ConsistsOf –> Facet)
      • 2. Patterns for “linked” (Association: Resource – IsRelatedTo –> Resource)
      • 3. Patterns for “pointing to” (Topological Edge Direction)
      • Architectural Rationale
  • Information System Model — Core Topology
    • Contexts as Logical Partitions
    • The Core Graph Model
      • Visual Taxonomy
      • Graph Topologies
        • Entities
        • Relations
      • Architectural Topology: Infrastructure vs Descriptive
        • Monolithic vs Modular Instances
        • Topological and Contextual Rules
        • Visibility vs Presence
        • System Fields
      • Property
      • Type
        • Schema
        • Subtyping and Polymorphism
        • Polymorphism in Relations (Source and Target)
        • The Open-World Assumption (Extensibility Paradigm)
        • Topological Uniqueness Invariants
        • Resource Structural Cardinality
          • ConsistsOf to Facet Cardinality
          • IsRelatedTo Suggestion
        • Schema-Mixed Mode (Custom Properties Extensibility)
        • Types as “First-Class Documentation”
      • The LEGO Metaphor
  • Information System Model — Mutations & Avalanches
    • Multi-Context Mutations
    • Add Propagation
    • Remove Propagation
    • Recursive Avalanche
    • Add and Remove Asymmetry
      • Scenario 1: add: propagate and remove: keep
      • Scenario 2: add: unpropagate and remove: cascade
    • Reference Counting
    • Comprehensive Scenario
      • Initial State
      • Scenario A: The Add Avalanche
      • Scenario B: Alternate Source Context
      • Scenario C: The Remove Avalanche
  • Resource Registry — Data Representation (Schemas)
    • Context Representation
      • Example: Context Hierarchy
        • Field Explanations
    • Type Schema Representation (Self-Describing API)
      • Resource Type Schema
        • Field Explanations
      • Facet Type Schema
        • Field Explanations
        • Property Naming Constraints (Normative)
      • IsRelatedTo Type Schema
        • Field Explanations
      • ConsistsOf Type Schema
        • Field Explanations
      • Property Type Schema
        • Field Explanations
  • Resource Registry — Data Representation (Instances)
    • Instance Representation
      • System-Generated Fields
        • Order of System Fields
        • type Field
        • supertypes Array
          • Type Linearization (Multiple Inheritance)
        • id Field (REST Profile Mandate)
        • Client Parsing Resilience (Open-World Extensibility)
        • metadata Field
          • lastUpdateTime Evaluation Logic
        • contexts Map
      • Examples: Base Instances
        • Resource Instance
        • Facet Instance
        • IsRelatedTo Instance
        • ConsistsOf Instance
    • Query Templates Representation
      • Example: Query Template Definition
        • Field Explanations
        • TemplateVariable Contract
    • Schema-Mixed Encrypted Fields
    • Operation Envelope Representation
      • Minimal Operation Envelope (Prefer: return=minimal)
      • Full Representation Operation Envelope (Prefer: return=representation)
  • Resource Registry — REST API Foundations & Roles
    • HTTP Protocol Foundations
      • HTTP Methods, Safety, and Idempotency
      • Normative Method Intent for Mutations (PUT vs PATCH)
        • The QUERY HTTP Method (RFC 10008) and POST Fallback
      • Omission of Standard Validation Errors (400) and List Authorization (403)
      • URL Convention
      • HTTP Request Headers
      • HTTP Response Headers
      • Status Codes
      • Error Catalogue & JSON Payload
      • Context-Agnostic System Fields
      • Idempotency in Structural Mutations (PUT)
    • REST API Design Principles
    • Roles
      • Authentication & Identity Context
      • Understanding Hierarchical Scope
      • IS-Manager and Infrastructure-Manager
      • IS-Admin
      • Context-Manager
      • IS-Editor
      • IS-Contributor
      • IS-Member
    • API Reference
    • Architectural Choices
      • Ecosystem Boundaries & Generalization Intent
      • Preemptive Architectural Explanations
    • Known Criticisms & Deliberate Deviations
  • Resource Registry — API Management (Contexts & Types)
    • Context Management — base path /contexts
      • Authorization & Token Selection
      • HTTP Contract
      • Operational Notes
      • Context Lifecycle State Machine
      • Inherited Operational State (effectiveState)
    • Type Management — base path /types
      • Authorization & Token Selection
      • HTTP Contract
      • Operational Notes
  • Resource Registry — API Management (Instances & Admin)
    • Instance Management — base path /instances
      • Authorization & Token Selection
      • HTTP Contract
      • Operational Notes
      • Contextual Mutations & Update Intent (PUT vs PATCH)
        • PATCH (Merge Semantic)
        • PUT on Resource Instances (Topological Impact)
          • 1. Single Context Update (Local Copy-on-Write)
          • 2. Subtree Synchronization (?syncExistingHierarchy=true)
          • 3. Hierarchical Distribution (?hierarchical=true)
        • PUT on Other Instances (Full Replace Semantic)
      • Membership Operations (Remove from Current Context / Add to Context)
      • Operation Envelope and Parameter Matrix
      • Try-Check-Confirm Pattern (dryRun=true)
      • DELETE vs /admin/ DELETE Paradigm (Reference Counting)
      • Additional Constraints
    • Admin API — base path /admin
      • Authorization & Token Selection
      • HTTP Contract
      • Operational Notes
      • High-Impact Topological Operations Summary
  • Resource Registry — API Access & Query Templates
    • Query Template Management — base path /query-templates
      • Authorization & Token Selection
      • HTTP Contract
      • Operational Notes
    • Access API — base path /access
      • Contexts, Types, Query Templates (mirrors)
      • Instances (mirrors)
      • Token Selection (Quick Rule)
  • Resource Registry — API Query Parameters Reference
    • Parameter Value Handling
    • Pagination Parameters
    • limit and offset
    • Behavioral Parameters
    • lifecycle
    • polymorphic
    • depth
    • hierarchical
      • Hierarchical Operations over Mixed-State Subtrees
    • syncExistingHierarchy
    • propagationMode
      • propagationMode (Add to Context)
      • propagationMode (Remove from Context)
    • dryRun
    • Inclusion Parameters
    • metadataPolicy
    • contextsPolicy
    • membershipScope
    • Privileged Parameters
    • rawResult — Raw Query only
    • bypassHierarchyCheck — Cross-Boundary Add
    • Parameter Conflicts
  • Information System — Architectural Explanations
    • Abandonment of Facet Sharing Across Resources
    • Architectural Abstraction: Reference Counting vs. Graph Internals
    • Hierarchical Graph Union: Pre-Computed Hierarchical Contexts
      • Two Different “Implicit” Behaviors in Point Reads
    • Contexts as Record-Level Security (RLS) Groups
      • Context Re-Parenting, Renaming, and Subtree Migration
    • “System” Environments (Infrastructure Metadata)
    • Type Evolution and Backwards Compatibility (Static vs Dynamic Schema)
    • Elimination of notnull as an Independent Property Constraint
    • The Structural Delta (Controlled Evolution vs Anarchy)
    • Query Template Evolution (Online but Admin-Gated)
    • Sensitive Values Are Queried Through the Caller-Visible Representation
    • Abandonment of RESTful Transactions in favor of Atomic Operations
    • No Bulk Setting of Context Memberships
    • Privileged Add to Context Uses the Canonical Membership Endpoint
    • Protocol Transparency in Error Handling
    • Over-Regulation vs. Pragmatic Power (The “Straitjacket” Fallacy)
    • The Nature of Federation: Modeling vs. Active Publishing
    • REST API: Collection URIs vs Schema Representations
    • Naming Conventions
    • REST API: Canonical Identifiers for System Objects (Name vs UUID)
    • REST API: Flat Addressability vs Nested ROA Paths
    • REST API: Mandatory Client-Supplied UUIDs for Structural Idempotency
    • The /admin Segregation for Whole-System and Destructive Operations
    • Scope Expansion: Context Hierarchy vs Type Polymorphism
      • Local vs. Subtree Operational Roles
      • Subtree Authority vs. Administrative Override
    • Membership Representation Uses an Independent Scope Axis
    • Authentication Ecosystem Abstraction (D4Science Implementation)
  • References
  • Information System Model — Formal Semantics
    • Type Theory
      • Typing Relation
      • Subtyping (Inheritance)
      • System Fields
      • Formal Topological Uniqueness Invariants
    • Set Theory for Context Membership
      • General Relation Context Intersection
      • Facet Context Dependency
      • Resource Context Union
      • Avalanche State Transitions
      • Reference Counting
  • Element Category Matrix
  • Complex Topology Scenarios — Cyclic Graphs
    • Part 1: The Remove Avalanche (Orphan Evaluation)
      • Visual Legend: Remove Avalanche
      • Step 1: The Initial Trigger
      • Step 2: Topological Cleanup of IRT42 and Cascading to R2
      • Step 3: Removing R2 and Evaluating its Outgoing Relations
      • Step 4: Removing R5 and Evaluating IRT56
      • Step 5: Removing R6, Evaluating IRT63, and the Post-State Orphan Check
      • Step 6: Removing R3 and Evaluating IRT31 and IRT37
      • Final Local Topology in C1
      • Final Global Topology
    • Part 2: The Add Avalanche (Cycle Breaking)
      • Visual Legend: Add Avalanche
      • Step 1: The Initial Trigger and the Visited Set
      • Step 2: Evaluating Outgoing Relations (shallow vs deep)
        • Step 3: Propagating from R5 to R6
        • Step 4: Propagating from R6 to R3
        • Step 5: Cycle Breaking on IRT35
        • Step 6: Propagating IRT37
        • Step 7: Halting on IRT31
        • Step 8: Final Cycle Break on IRT23
        • Final Global Topology
  • Response Shape Matrix
    • Base Response Shape
    • Payload Enrichment Modifiers
  • Resource Registry — API Operational Cookbook & Advanced Use Cases
    • The Shared Instance Mutation (Global Effect for Facets and Relations)
    • Context-Local Instance Forking (Copy-on-Write)
    • The Cardinality Chicken-and-Egg (min: 1, max: 1)
    • Hierarchical Downstream Mutations (hierarchical vs syncExistingHierarchy)
      • The Surgical Sync (?syncExistingHierarchy=true)
      • The Blanket Replication (?hierarchical=true)
    • Surgical Relation instance / Entity instance Deletion (?propagationMode=surgical)
    • Descriptive-Topology Closure on Direct Relation Add
    • Canonical Mutation Semantics: PUT (Replace Intent) vs PATCH (Merge Intent)
      • PUT Replace Intent (example)
      • PATCH Merge Intent (example)
    • Moving or Renaming a Context: Previous Paths
      • Reparenting a VRE
      • Renaming a VO: the Cascade
      • A Token with an Old Path
      • Replacing the Previous Paths
      • Reusing a Path
  • Resource Registry Ecosystem: Tooling & Clients
    • The information-system-model Library
      • Type Generation via Annotations
      • Model Extension Discovery
      • Marshalling, Unmarshalling, and Utilities
    • Automated Documentation Generator
    • Modular REST Clients
      • Client API Alignment & Parity
      • Request Options and Response Metadata
      • Summary
  • JSON Query Syntax Reference
    • Core Principles
    • Depth-Based Type-Name Matching (Type-Definition Queries Only)
    • Response Projection (_emit)
      • Sensitive Metadata Predicates
      • Canonical _emit Precedence Rules
      • Projecting Context Fields
      • Projecting Type Schema Fields
      • Projecting Instance Fields
      • Deep Projection
      • Projecting QueryTemplate Fields
    • Computed Values
    • Logical Operators
      • _or (Match ANY condition)
      • _and (Match ALL conditions)
      • _not (Match when the condition does NOT hold)
    • Comparison Operators
      • Scalar and Presence Operators
      • Collection and Map Operators
    • Inverse Traversal (_source)
      • Example: Finding the EService that owns a specific StateFacet
    • Query Templates (Variables)
  • HATEOAS Navigation Controls
    • Endpoint Relation Matrix
    • Architectural & Semantic Notes
      • Following Pagination Links of a Query
      • The Deliberate Omission of rel="last"
      • Semantic Resolution of up, parent, and supertype
      • Schema Discovery via rel="type"
      • Header Syntax for Multiple Links
  • X-Result-Scope Conventions
    • Normative Values
      • Examples
      • Multiple Scope Modifiers (Formatting)

Guides (non-normative)

  • Naming Query Templates
    • The rule
    • The description
    • Macro-groups
    • Why the macro-group and not the component
    • Changing a name
    • Who installs a template
Resource Registry Service
  • »
  • Search

© Copyright 2016, Luca Frosini (D4Science Infrastructure).

Built with Sphinx using a theme provided by Read the Docs.