In our experience with SDML we have seen multiple cases of entities (and structures, but we will use entities as our
example here) where the presence or absence of fields is dependent on the state of the entity. To model this we have
@@ -322,9 +322,9 @@
Introduction
-
-
Motivation
-
+
+
2. Motivation
+
One common use for constraints in our domain model is to define the cardinality of fields under certain conditions;
especially to make them optional or required depending on the state of the entity. In programming languages there is an
@@ -339,7 +339,7 @@
Motivation
that the state Closed is a terminal state as it has no operations and so nothing can be legally done with it.
-
+
type FileHandle {
state {
fn open(path): Self[Open];
@@ -358,7 +358,7 @@
Motivation
would be possible, as in:
-
+
type FileHandle {
state {
}
@@ -371,14 +371,14 @@
Motivation
-
-
Alternatives Considered
-
+
+
3. Alternatives Considered
+
-
-
States with fields
-
-
+
+
3.1. States with fields
+
+
entity Shipment is
identity id -> gs1:ShipmentIdentifier
@@ -421,10 +421,10 @@
States with fields
-
-
Simple field constraints
-
-
+
+
3.2. Simple field constraints
+
+
union ShipmentStates of
Created
Planned
@@ -449,7 +449,7 @@
Simple field constraints
end
-
+
units -> {1..} gs1:LogisticsUnitIdentifier is
assert state_cardinality is
self.container.state = Created implies self.min_occurs >= 1
@@ -457,10 +457,10 @@
Simple field constraints
-
-
States separate from fields
-
-
+
+
3.3. States separate from fields
+
+
entity Shipment is
identity id -> gs1:ShipmentIdentifier
@@ -487,7 +487,7 @@
States separate from fields
-
+
Figure 1: Example State Machine
@@ -495,10 +495,10 @@
States separate from fields
-
-
Potential de-sugaring
-
-
+
+
3.4. Potential de-sugaring
+
+
structure ShipmentPlanned is
units -> {1..} gs1:LogisticsUnitIdentifier
end
@@ -543,9 +543,9 @@
Potential de-sugaring
-
-
Proposed Change
-
+
+
4. Proposed Change
+
The following changes are required:
@@ -555,18 +555,18 @@
Proposed Change
-
-
Test cases
-
+
+
4.1. Test cases
+
What test cases do you intend to include.
-
-
Impact
-
+
+
4.2. Impact
+
What is the scope of the impact, this should relate to any tags you
added to the section in the index file.
@@ -576,7 +576,7 @@
+It turns out to be confusing to use existing structure types to define new RDF classes and properties. Rather than
+continuing to document rules on composition and restrictions on some RDF predicates we regularize these into new
+explicit definitions.
+
+
+
+
+
+
2. Motivation
+
+
+Why is there a problem, or a potential opportunity. Please include examples.
+
+
+
+
+
+
3. Alternatives Considered
+
+
+This is a good way to describe the thinking behind the proposed change or
+changes.
+
+
+
+
+
+
4. Proposed Change
+
+
+The following changes are required:
+
+
+
+
Add a new rdf_def rule to the grammar that defines either a class or property using an annotaion_only_body.
+
Add specific rules rdf_type_class and rdf_type_property for the distinct keywords.
+
Add the new rule rdf_def to the existing definition rule.
modulerdf_schema<http://www.w3.org/2000/01/rdf-schema#>is
+
+ import[owlrdf]
+
+ structureFoois a ->stringend
+
+ rdfstructureResourceis;; assumed: @rdf:type = rdf:Class
+ @comment="The class resource, everything."
+ end
+
+ rdfpropertysubClassOfis;; assumed: @rdf:type = rdf:Property
+ @domain=Class
+ @range=Class
+ @comment="The subject is a subclass of a class."
+ end
+
+ rdfpropertycommentis
+ @rdf:type=owl:AnnotationProperty
+ @domain=Resource
+ @range=Literal
+ @comment="A description of the subject resource."
+ end
+
+end
+
+
+
+
+
+
4.1. Test cases
+
+
+
The module in listing 3 is included in the tree-sitter-sdml package in the examples directory
+which is included in the parser test step.
+
An explicit test case, rdf_definitions.sdm has been added to the tree-sitter-sdml test/corpus directory.
+
An explicit test case, rdf_definitions.sdm has been added to the sdml-parse crate’s tests/examples directory.
+
+
+
+
+
+
4.2. Impact
+
+
+This will require changes to the reference documentation to:
+
+
+
+
add new rules to sdml.ebnf,
+
update the surface syntax description to include these new rules, and
+
rewrite the section on defining new RDF properties and classes.
+
+
+
+This will change how we define standard library modules as well.
+
+
+
+
+
+
+
Created: 2024-01-18 Thu 08:45
+
+
+
diff --git a/docs/rfcs/005-rdf-definitions.org b/docs/rfcs/005-rdf-definitions.org
new file mode 100644
index 0000000..21505bd
--- /dev/null
+++ b/docs/rfcs/005-rdf-definitions.org
@@ -0,0 +1,115 @@
+#+TITLE: RFC005: Explicit RDF definitions
+#+SUBTITLE: Status: Approved
+#+AUTHOR: Primary Author
+#+EMAIL: johnstonskj@gmail.com
+#+LANGUAGE: en
+#+OPTIONS: author:nil created:nil creator:nil date:nil email:nil num:3 toc:t
+#+HTML_HEAD:
+#+HTML_LINK_HOME: ./index.html
+#+HTML_LINK_UP: ./index.html
+
+
+* Introduction
+
+It turns out to be confusing to use existing structure types to define new RDF classes and properties. Rather than
+continuing to document rules on composition and restrictions on some RDF predicates we regularize these into new
+explicit definitions.
+
+* Motivation
+
+The current use of standard structures to define RDF classes and properties is cumbersome.
+
+* Alternatives Considered
+
+None.
+
+* Proposed Change
+
+The following changes are required:
+
+1. Add a new ~rdf_def~ rule to the grammar that defines either a class or property using an ~annotaion_only_body~.
+2. Add specific rules ~rdf_type_class~ and ~rdf_type_property~ for the distinct keywords.
+3. Add the new rule ~rdf_def~ to the existing ~definition~ rule.
+
+#+NAME: src:grammar-rdf_def
+#+CAPTION: Grammar for ~rdf_def~ rule
+#+BEGIN_SRC js :eval never
+rdf_def: $ => seq(
+ keyword('rdf'),
+ field(
+ 'type',
+ choice(
+ $.rdf_type_class,
+ $.rdf_type_property,
+ )
+ ),
+ field('name', $.identifier),
+ field('body', $.annotation_only_body)
+),
+
+rdf_type_class: $ => keyword('structure'),
+
+rdf_type_property: $ => keyword('property'),
+#+END_SRC
+
+#+NAME: src:grammar-definition
+#+CAPTION: Grammar for ~definition~ rule
+#+BEGIN_SRC js :eval never
+definition: $ => choice(
+ $.data_type_def,
+ $.entity_def,
+ $.enum_def,
+ $.event_def,
+ $.property_def,
+ $.structure_def,
+ $.type_class_def,
+ $.union_def,
+ $.rdf_def
+),
+#+END_SRC
+
+#+NAME: src:rdf_schema-example
+#+CAPTION: Example Module
+#+BEGIN_SRC sdml :eval never
+module rdf_schema is
+
+ import [ owl rdf ]
+
+ structure Foo is a -> string end
+
+ rdf structure Resource is ;; assumed: @rdf:type = rdf:Class
+ @comment = "The class resource, everything."
+ end
+
+ rdf property subClassOf is ;; assumed: @rdf:type = rdf:Property
+ @domain = Class
+ @range = Class
+ @comment = "The subject is a subclass of a class."
+ end
+
+ rdf property comment is
+ @rdf:type = owl:AnnotationProperty
+ @domain = Resource
+ @range = Literal
+ @comment = "A description of the subject resource."
+ end
+
+end
+#+END_SRC
+
+** Test cases
+
+1. The module in listing [[src:rdf_schema-example]] is included in the tree-sitter-sdml package in the =examples= directory
+ which is included in the parser test step.
+2. An explicit test case, =rdf_definitions.sdm= has been added to the tree-sitter-sdml =test/corpus= directory.
+3. An explicit test case, =rdf_definitions.sdm= has been added to the sdml-parse crate's =tests/examples= directory.
+
+** Impact
+
+This will require changes to the reference documentation to:
+
+- add new rules to =sdml.ebnf=,
+- update the surface syntax description to include these new rules, and
+- rewrite the section on defining new RDF properties and classes.
+
+This will change how we define standard library modules as well.
diff --git a/docs/rfcs/index.html b/docs/rfcs/index.html
index 6b125c3..d729eab 100644
--- a/docs/rfcs/index.html
+++ b/docs/rfcs/index.html
@@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
+
SDML RFCs
@@ -201,10 +201,11 @@
