rl2-shacl.ttl

@prefix sh:   <http://www.w3.org/ns/shacl#> .
@prefix rl2:  <https://rl2.example/ontology#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

############################################################
# RL2 SHACL Shapes
# Syntax validation for RL2 policies
############################################################
#
# Design Principles:
#
# 1. NOT CLOSED SHAPES
#    These shapes are intentionally non-closed (no sh:closed true).
#    This allows profiles and implementations to extend RL2 classes
#    with additional properties without breaking validation.
#
# 2. PROFILE FLEXIBILITY
#    Certain classes are intentionally left without shapes or with
#    minimal constraints:
#    - Agent: Open-ended; may be users, organizations, services, etc.
#    - Action: Profile-defined (e.g., media: play, stream; software:
#      execute, install; data governance: process, transfer)
#    - Asset: Open-ended; any resource subject to normative control
#    - LeftOperand: Profile-defined (e.g., purpose, dateTime, spatial)
#
#    This design enables domain-specific profiles to define their own
#    actions, assets, and operands without modifying core shapes.
#
# 3. POLICY SUBCLASS INHERITANCE
#    Policy subtypes (Set, Offer, Privacy, Assertion) inherit from
#    PolicyShape via SHACL's standard inheritance behavior. Only
#    Agreement has an additional shape requiring grantor/grantee.
#
# 4. STATE ENUMERATION VALIDATION
#    ObligationState and PromiseState are constrained to their
#    respective valid values defined in the ontology.
#
############################################################

# Policy shape - validates policy structure
rl2:PolicyShape a sh:NodeShape ;
    sh:targetClass rl2:Policy ;
    sh:property [
        sh:path rl2:clause ;
        sh:minCount 1 ;
        sh:class rl2:Norm ;
        sh:message "A policy must have at least one clause (norm)."
    ] ;
    sh:property [
        sh:path rl2:grantor ;
        sh:maxCount 1 ;
        sh:class rl2:Agent
    ] ;
    sh:property [
        sh:path rl2:grantee ;
        sh:maxCount 1 ;
        sh:class rl2:Agent
    ] ;
    sh:property [
        sh:path rl2:condition ;
        sh:maxCount 1 ;
        sh:class rl2:Condition ;
        sh:message "A policy may have at most one activation condition."
    ] ;
    sh:property [
        sh:path rl2:policyGeneration ;
        sh:maxCount 1 ;
        sh:datatype xsd:anyURI
    ] .

# Agreement requires both grantor and grantee
rl2:AgreementShape a sh:NodeShape ;
    sh:targetClass rl2:Agreement ;
    sh:property [
        sh:path rl2:grantor ;
        sh:minCount 1 ;
        sh:message "An Agreement must identify a grantor."
    ] ;
    sh:property [
        sh:path rl2:grantee ;
        sh:minCount 1 ;
        sh:message "An Agreement must identify a grantee."
    ] .

# Privilege shape
rl2:PrivilegeShape a sh:NodeShape ;
    sh:targetClass rl2:Privilege ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ] ;
    sh:property [ sh:path rl2:action ; sh:minCount 1 ; sh:class rl2:Action ] ;
    sh:property [ sh:path rl2:object ; sh:minCount 1 ] .

# Duty shape
rl2:DutyShape a sh:NodeShape ;
    sh:targetClass rl2:Duty ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ] ;
    sh:property [ sh:path rl2:action ; sh:minCount 1 ; sh:class rl2:Action ] ;
    sh:property [ sh:path rl2:object ; sh:minCount 1 ] .

# Prohibition shape
rl2:ProhibitionShape a sh:NodeShape ;
    sh:targetClass rl2:Prohibition ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ] ;
    sh:property [ sh:path rl2:prohibitedAction ; sh:minCount 1 ; sh:class rl2:Action ] ;
    sh:property [ sh:path rl2:object ; sh:minCount 1 ] .

# Claim shape (Hohfeldian correlative to Duty)
rl2:ClaimShape a sh:NodeShape ;
    sh:targetClass rl2:Claim ;
    sh:property [ sh:path rl2:claimHolder ; sh:minCount 1 ; sh:class rl2:Agent ;
        sh:message "A Claim must identify a claimHolder (the right-holder)." ] ;
    sh:property [ sh:path rl2:claimAgainst ; sh:minCount 1 ; sh:class rl2:Agent ;
        sh:message "A Claim must identify a claimAgainst (the duty-bearer)." ] .

# Power shape (ability to alter normative relations)
rl2:PowerShape a sh:NodeShape ;
    sh:targetClass rl2:Power ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ;
        sh:message "A Power must identify a subject (the power-holder)." ] ;
    sh:property [ sh:path rl2:affectsNorm ; sh:minCount 1 ; sh:class rl2:Norm ;
        sh:message "A Power must identify the norm it can affect." ] .

# Liability shape (exposure to exercise of power)
rl2:LiabilityShape a sh:NodeShape ;
    sh:targetClass rl2:Liability ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ;
        sh:message "A Liability must identify a subject (the exposed party)." ] ;
    sh:property [ sh:path rl2:exposedTo ; sh:minCount 1 ; sh:class rl2:Power ;
        sh:message "A Liability must identify the power it is exposed to." ] .

# Immunity shape (protection against power)
rl2:ImmunityShape a sh:NodeShape ;
    sh:targetClass rl2:Immunity ;
    sh:property [ sh:path rl2:subject ; sh:minCount 1 ; sh:class rl2:Agent ;
        sh:message "An Immunity must identify a subject (the protected party)." ] ;
    sh:property [ sh:path rl2:immuneFrom ; sh:minCount 1 ; sh:class rl2:Power ;
        sh:message "An Immunity must identify the power it protects against." ] .

# Promise shape
rl2:PromiseShape a sh:NodeShape ;
    sh:targetClass rl2:Promise ;
    sh:property [ sh:path rl2:promisor ; sh:minCount 1 ; sh:class rl2:Agent ] ;
    sh:property [ sh:path rl2:promisee ; sh:minCount 1 ; sh:class rl2:Agent ] ;
    sh:property [
        sh:path rl2:promiseContent ;
        sh:minCount 1 ;
        sh:xone (
            [ sh:class rl2:Action ]
            [ sh:class rl2:Duty ]
            [ sh:class rl2:Condition ]
        ) ;
        sh:message "Promise content must be an Action, Duty, or Condition."
    ] .

############################################################
# Condition Shapes
############################################################

# Atomic constraints are simple comparisons (leftOperand, operator, rightOperand).
# Note: This shape targets rl2:AtomicConstraint specifically, not the base Condition class,
# to avoid false positives with SHACL engines that perform RDFS inference on subclasses.
rl2:AtomicConstraintShape a sh:NodeShape ;
    sh:targetClass rl2:AtomicConstraint ;
    sh:property [ sh:path rl2:leftOperand ; sh:minCount 1 ] ;
    sh:property [ sh:path rl2:constraintOperator ; sh:minCount 1 ; sh:class rl2:ComparisonOperator ] ;
    sh:property [
        sh:path rl2:targetNorm ;
        sh:maxCount 1 ;
        sh:class rl2:Norm ;
        sh:message "targetNorm must reference a Norm."
    ] ;
    sh:xone (
        [ sh:property [
            sh:path rl2:rightOperand ;
            sh:minCount 1 ;
            sh:nodeKind sh:Literal ;
            sh:message "rightOperand must be a literal value."
        ] ]
        [ sh:property [
            sh:path rl2:rightOperandRef ;
            sh:minCount 1 ;
            sh:nodeKind sh:IRI ;
            sh:message "rightOperandRef must be an IRI reference."
        ] ]
    ) .

# Conditional requirement: targetNorm REQUIRED for norm state operands.
# When leftOperand is obligationStateOperand or dutyPerformerOperand,
# the constraint must specify which norm's state to query.
rl2:NormStateConstraintShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this a rl2:AtomicConstraint ;
                      rl2:leftOperand ?op .
                FILTER(?op IN (rl2:obligationStateOperand, rl2:dutyPerformerOperand))
            }
        """
    ] ;
    sh:property [
        sh:path rl2:targetNorm ;
        sh:minCount 1 ;
        sh:class rl2:Norm ;
        sh:message "AtomicConstraint with obligationStateOperand or dutyPerformerOperand must specify targetNorm."
    ] .

# Logical constraints combine sub-conditions via logical operators.
# Note: The 'not' operator requires exactly one operand; 'and', 'or', 'xone' require
# at least two. This shape validates the minimum; implementations should enforce
# operator-specific cardinality as defined in the ontology comments.
rl2:LogicalConstraintShape a sh:NodeShape ;
    sh:targetClass rl2:LogicalConstraint ;
    sh:property [ sh:path rl2:constraintOperator ; sh:minCount 1 ; sh:class rl2:LogicalOperator ] ;
    sh:property [ sh:path rl2:operand ; sh:minCount 1 ; sh:class rl2:Condition ] .

# Operand cardinalities for logical operators
rl2:NotOperandCardinalityShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this a rl2:LogicalConstraint ;
                      rl2:constraintOperator rl2:not .
            }
        """
    ] ;
    sh:property [
        sh:path rl2:operand ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:message "The 'not' operator must have exactly one operand."
    ] .

rl2:AndOrXoneOperandCardinalityShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this a rl2:LogicalConstraint ;
                      rl2:constraintOperator ?op .
                FILTER(?op IN (rl2:and, rl2:or, rl2:xone))
            }
        """
    ] ;
    sh:property [
        sh:path rl2:operand ;
        sh:minCount 2 ;
        sh:message "The 'and', 'or', and 'xone' operators must have at least two operands."
    ] .


# Event constraints require an expected event
rl2:EventConstraintShape a sh:NodeShape ;
    sh:targetClass rl2:EventConstraint ;
    sh:property [ sh:path rl2:expectsEvent ; sh:minCount 1 ; sh:class rl2:Event ] .

# Asset collection shape
rl2:AssetCollectionShape a sh:NodeShape ;
    sh:targetClass rl2:AssetCollection ;
    sh:property [
        sh:path rl2:member ;
        sh:class rl2:Asset
    ] .

############################################################
# Operational Layer Shapes
############################################################

# Event shape - basic validation for events
rl2:EventShape a sh:NodeShape ;
    sh:targetClass rl2:Event ;
    sh:property [
        sh:path rl2:eventTime ;
        sh:maxCount 1 ;
        sh:datatype xsd:dateTime ;
        sh:message "An Event may have at most one event time."
    ] ;
    sh:property [
        sh:path rl2:operationalAgent ;
        sh:maxCount 1 ;
        sh:class rl2:Agent ;
        sh:message "An Event may have at most one operational agent."
    ] .

# State transition shape
rl2:StateTransitionShape a sh:NodeShape ;
    sh:targetClass rl2:StateTransition ;
    sh:property [
        sh:path rl2:triggeredBy ;
        sh:minCount 1 ;
        sh:class rl2:Event ;
        sh:message "A StateTransition must be triggered by an Event."
    ] ;
    sh:property [
        sh:path rl2:fromState ;
        sh:minCount 1 ;
        sh:message "A StateTransition must specify the originating state."
    ] ;
    sh:property [
        sh:path rl2:toState ;
        sh:minCount 1 ;
        sh:message "A StateTransition must specify the resulting state."
    ] .

# Duty state validation - ensure valid obligation state
rl2:DutyStateShape a sh:NodeShape ;
    sh:targetClass rl2:Duty ;
    sh:property [
        sh:path rl2:obligationState ;
        sh:maxCount 1 ;
        sh:in (rl2:Pending rl2:Active rl2:Fulfilled rl2:Violated) ;
        sh:message "Duty obligationState must be one of: Pending, Active, Fulfilled, Violated."
    ] .

# Promise state validation - ensure valid promise state
rl2:PromiseStateShape a sh:NodeShape ;
    sh:targetClass rl2:Promise ;
    sh:property [
        sh:path rl2:promiseState ;
        sh:maxCount 1 ;
        sh:in (rl2:Pending rl2:Fulfilled rl2:Violated) ;
        sh:message "Promise promiseState must be one of: Pending, Fulfilled, Violated (promises do not use Active)."
    ] .

# Norm priority validation - ensure valid integer
rl2:NormPriorityShape a sh:NodeShape ;
    sh:targetClass rl2:Norm ;
    sh:property [
        sh:path rl2:priority ;
        sh:maxCount 1 ;
        sh:datatype xsd:integer ;
        sh:message "Norm priority must be an integer."
    ] .

############################################################
# Additional consistency checks
############################################################

# Ensure state.Events.<Type> uses a declared Event type (or wildcard)
rl2:EventPathTypeShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this ?path WHERE {
                ?this rl2:resolutionPath ?path .
                FILTER(STRSTARTS(?path, "state.Events."))
                FILTER(?path != "state.Events.*" && !STRSTARTS(?path, "state.Events.*."))
            }
        """
    ] ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message "resolutionPath segment after state.Events must be an Event type IRI declared in the graph, or use wildcard *." ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT $this ?path WHERE {
                $this rl2:resolutionPath ?path .
                FILTER(STRSTARTS(?path, "state.Events."))
                FILTER(?path != "state.Events.*" && !STRSTARTS(?path, "state.Events.*."))
                BIND(REPLACE(?path, "^state\\.Events\\.([^\\.]+).*$", "$1") AS ?etypeLex)
                FILTER NOT EXISTS {
                    ?etype a rl2:Event .
                    FILTER(STR(?etype) = ?etypeLex || STRAFTER(STR(?etype), "#") = ?etypeLex || STRENDS(STR(?etype), ?etypeLex))
                }
            }
        """
    ] .

# Enforce targetNorm for norm state operands (already covered) and add type check for rightOperand vs leftOperand range
rl2:OperandRangeTypeShape a sh:NodeShape ;
    sh:targetClass rl2:AtomicConstraint ;
    sh:severity sh:Warning ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message "If leftOperand declares rdfs:range and rightOperand is an IRI, rightOperand should have that type." ;
        sh:select """
            PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT $this WHERE {
                $this rl2:leftOperand ?op ;
                      rl2:rightOperand ?right .
                ?op rdfs:range ?expected .
                FILTER(isIRI(?right))
                FILTER NOT EXISTS { ?right a ?expected }
            }
        """
    ] .

############################################################
# Profile-Declared Operand Shapes
############################################################
#
# These shapes validate profile-declared left operands and their
# resolution mechanisms. Operands should declare either a
# resolutionPath (for deref-based resolution) or a resolutionFunction
# (for implementation-specific function calls).
#
# The path root validation shape ensures resolution paths use only
# canonical roots: agent, asset, state, context, request.

# LeftOperand shape - validates profile-declared operands
rl2:LeftOperandShape a sh:NodeShape ;
    sh:targetClass rl2:LeftOperand ;
    sh:property [
        sh:path rl2:resolutionPath ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
        sh:message "resolutionPath must be a string path expression."
    ] ;
    sh:property [
        sh:path rl2:resolutionFunction ;
        sh:maxCount 1 ;
        sh:datatype xsd:string ;
        sh:message "resolutionFunction must be a function name string."
    ] .

# Path root validation - ensures resolution paths use canonical roots
# This shape validates that resolutionPath values start with allowed roots.
# Canonical roots: agent, asset, state, context, request
rl2:ResolutionPathRootShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this rl2:resolutionPath ?path .
            }
        """
    ] ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message "resolutionPath must start with a canonical root: agent, asset, state, context, or request." ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT $this ?path WHERE {
                $this rl2:resolutionPath ?path .
                FILTER(
                    !STRSTARTS(?path, "agent.") &&
                    !STRSTARTS(?path, "asset.") &&
                    !STRSTARTS(?path, "state.") &&
                    !STRSTARTS(?path, "context.") &&
                    !STRSTARTS(?path, "request.") &&
                    ?path != "agent" &&
                    ?path != "asset" &&
                    ?path != "state" &&
                    ?path != "context" &&
                    ?path != "request"
                )
            }
        """
    ] .

# Operand resolution recommendation - warn if neither path nor function specified
# This is a WARNING-level shape (sh:severity sh:Warning) since operands may
# use legacy external resolution or be core operands with built-in resolution.
rl2:OperandResolutionRecommendationShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this a rl2:LeftOperand .
                FILTER NOT EXISTS { ?this rl2:resolutionPath ?p }
                FILTER NOT EXISTS { ?this rl2:resolutionFunction ?f }
                FILTER(?this NOT IN (rl2:obligationStateOperand, rl2:dutyPerformerOperand, rl2:currentDateTime))
            }
        """
    ] ;
    sh:severity sh:Warning ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message "Profile-declared LeftOperand should specify either resolutionPath or resolutionFunction for explicit resolution semantics." ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT $this WHERE {
                $this a rl2:LeftOperand .
                FILTER NOT EXISTS { $this rl2:resolutionPath ?p }
                FILTER NOT EXISTS { $this rl2:resolutionFunction ?f }
            }
        """
    ] .

# AtomicConstraint leftOperand validation - ensure leftOperand is a LeftOperand
rl2:AtomicConstraintLeftOperandShape a sh:NodeShape ;
    sh:targetClass rl2:AtomicConstraint ;
    sh:property [
        sh:path rl2:leftOperand ;
        sh:class rl2:LeftOperand ;
        sh:message "leftOperand must be an instance of rl2:LeftOperand."
    ] .

############################################################
# Identity Binding Security Shapes
############################################################
#
# These shapes enforce secure patterns for identity binding
# comparisons. When comparing dynamic operands (like dutyPerformerOperand)
# the right side should also be a runtime reference (like currentAgent),
# not a hardcoded IRI that would bypass dynamic binding semantics.
#

# Dynamic operand pairing - rightOperandRef must be RuntimeReference
# when leftOperand is dutyPerformerOperand
#
# This prevents patterns like:
#   rl2:leftOperand rl2:dutyPerformerOperand ;
#   rl2:rightOperandRef ex:Bob .  # INSECURE: hardcoded identity
#
# Correct pattern:
#   rl2:leftOperand rl2:dutyPerformerOperand ;
#   rl2:rightOperandRef rl2:currentAgent .  # SECURE: dynamic binding
#
rl2:DynamicOperandPairingShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this a rl2:AtomicConstraint ;
                      rl2:leftOperand rl2:dutyPerformerOperand ;
                      rl2:rightOperandRef ?ref .
            }
        """
    ] ;
    sh:severity sh:Warning ;
    sh:property [
        sh:path rl2:rightOperandRef ;
        sh:class rl2:RuntimeReference ;
        sh:message """Security warning: When leftOperand is dutyPerformerOperand, 
rightOperandRef should be a RuntimeReference (e.g., rl2:currentAgent) 
rather than a static IRI. Hardcoded identity comparisons bypass dynamic 
binding semantics and may create security vulnerabilities."""
    ] .

# Wildcard path requires EventConstraint sibling
# When using state.Events.* wildcard paths, the containing LogicalConstraint
# should include an EventConstraint to specify which event type to select.
rl2:WildcardEventConstraintShape a sh:NodeShape ;
    sh:target [
        a sh:SPARQLTarget ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT ?this WHERE {
                ?this rl2:resolutionPath ?path .
                FILTER(CONTAINS(?path, "state.Events.*"))
            }
        """
    ] ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message """Wildcard path state.Events.* should be accompanied by an EventConstraint 
in the same LogicalConstraint to specify which event type to select. 
Without an EventConstraint, the wildcard may match unintended events.""" ;
        sh:select """
            PREFIX rl2: <https://rl2.example/ontology#>
            SELECT $this WHERE {
                $this rl2:resolutionPath ?path .
                FILTER(CONTAINS(?path, "state.Events.*"))
                # Find the constraint using this operand
                ?constraint rl2:leftOperand $this .
                # Check if there's a sibling EventConstraint in same LogicalConstraint
                FILTER NOT EXISTS {
                    ?logical rl2:operand ?constraint ;
                             rl2:operand ?eventConstraint .
                    ?eventConstraint a rl2:EventConstraint .
                }
                # Also check if constraint itself is in a LogicalConstraint with EventConstraint
                FILTER NOT EXISTS {
                    ?logical2 rl2:operand $this ;
                              rl2:operand ?ec2 .
                    ?ec2 a rl2:EventConstraint .
                }
            }
        """
    ] .