Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document ID constraints for non element nodes #934

Open
goneall opened this issue Dec 5, 2024 · 6 comments
Open

Document ID constraints for non element nodes #934

goneall opened this issue Dec 5, 2024 · 6 comments
Labels
documentation Improvements or additions to documentation
Milestone

Comments

@goneall
Copy link
Member

goneall commented Dec 5, 2024

During the discussion on resolving the Individual Creation Infos, the issue was raised that we are not properly documenting the ID constraints for non Element classes.

We should document this this either in the model, serialization spec, or the using repo - actual location TBD.

@goneall goneall added the documentation Improvements or additions to documentation label Dec 5, 2024
@goneall goneall added this to the 3.1 milestone Dec 5, 2024
@goneall
Copy link
Member Author

goneall commented Dec 5, 2024

From previous minutes and discussions:

CreationInfo
Summary
Provides information about the creation of the Element.
Description
The CreationInfo provides information about who created the Element, and when and how it was created. 
The dateTime created is often the date of last change (e.g., a git commit date), not the date when the SPDX data was created, as doing so supports reproducible builds.
Metadata
name: CreationInfo
Instantiability: Concrete
Properties
< id > a globally unique URI identifier must be present for all instances of this class in deserialized form. In serialized form an identifier may be present for instances of this class as a globally unique URI identifier, as a locally unique string identifier, or not present at all if the instance of this class is embedded (e.g., blank node) within the instance of an Element class it is characterizing. Specific identifier requirements including presence, form, and property name for any given serialization form are defined in the relevant serialization binding rules.
model constraints
type: xsd:anyURI
minCount: 1
maxCount: 1
serialization constraints
type: xsd:string
maxCount: 1
specVersion
type: SemVer
minCount: 1
maxCount: 1
comment
type: xsd:string
minCount: 0
maxCount: 1
created
type: DateTime
minCount: 1
maxCount: 1
createdBy
type: Agent
minCount: 1
createdUsing
type: Tool
minCount: 0

@goneall
Copy link
Member Author

goneall commented Dec 5, 2024

Note related issue #805

@goneall
Copy link
Member Author

goneall commented Dec 5, 2024

Note that the git history does not show the above changes, they are from prior minutes.

@goneall
Copy link
Member Author

goneall commented Dec 8, 2024

In my experience, a relatively small percentage of SPDX implementers use or follow RDF standards, so I think it is important that we write the documentation in a way that makes sense to all audiences.

At the same time, we do need to communicate the difference between element IDs and non element class ids for graph implementations.

Based on this - I would propose we write up documentation in the context of describing what an SPDX Element is and how it differs from other classes in a general sense. We could then write up more specific implementation advice if coming from the RDF perspective.

Concepts that we could communicate:

  • Elements are the "atomic" unit of data to be transferred or exchanged
  • Elements must have a globally unique ID in the form of a URI
  • Elements can be externally referenced
  • Any properties of elements which are not themselves elements need to be exchanged along with the element
  • In RDF, non-element properties can be blank nodes
  • Non-element properties are not intended to be shared externally - the SPDX standard does not provide a mechanism for validating external non-element properties like it does for element properties.

@goneall
Copy link
Member Author

goneall commented Dec 8, 2024

@sbarnum - Thoughts on the above?

@goneall
Copy link
Member Author

goneall commented Dec 9, 2024

From discussion on the outreach call - idea is to start the documentation with a statement that there are 2 communities or two approaches we are trying solve:

  • Pure RDF graph implementations - highly granular
  • SPDX 2.X compatible document exchange implementations

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant