Merge pull request #365 from SynBioDex/SBOL3

Merge SBOL3 Specification to Master

.github/workflows/main.yml

@@ -1,9 +1,5 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI
 
-# Controls when the action will run. Triggers the workflow on push or pull request 
-# events but only for the master branch
 on:
   push:
     branches: [ SBOL3 ]

.gitignore

@@ -1,10 +1,16 @@
 .DS_Store
-sbol2.aux
-sbol2.bbl
-sbol2.blg
-sbol2.cb
-sbol2.cb2
-sbol2.log
-sbol2.out
-sbol2.pdf
-sbol2.toc
+sbol3.aux
+sbol3.bbl
+sbol3.blg
+sbol3.cb
+sbol3.cb2
+sbol3.log
+sbol3.out
+sbol3.pdf
+sbol3.toc
+jib.cls
+jib_abstract_3_0.aux
+jib_abstract_3_0.log
+jib_abstract_3_0.out
+jib_abstract_3_0.pdf
+*.gz

Dockerfile

@@ -3,5 +3,5 @@ FROM alpine:3.9.2
 
 RUN apk add texlive-full
 
-CMD ["/bin/sh", "-c", "cd /opt/spec && ./compile sbol2"]
+CMD ["/bin/sh", "-c", "cd /opt/spec && ./compile sbol3"]
 

README.md

@@ -4,7 +4,7 @@ This repository contains the master specification document for the SBOL data mod
 
 Members of the SBOL Development Community may use the issue tracker to flag problems with the existing specification and review ongoing issues under consideration.
 
-# Submitting changes to the specification
+## Submitting changes to the specification
 
 Before writing text for a non-trivial change, please have it approved by discussion as an Issue and/or SEP.
 
@@ -23,7 +23,20 @@ Here is an example of git commands to achieve this:
 When you are ready for your changes to be reviewed for incorporation, create a pull request.
 If you need help on pull requests see: https://help.github.com/articles/about-pull-requests/
 
-# Building the PDF from LateX
+## Automation
+
+This repository uses a [Github Action](https://github.com/features/actions) to automatically build the project when a pull request is made to the `SBOL3` branch, or a push is made to the branch (inlcuding when a PR is merged).
+This creates a PDF and uploads it as as a [workflow artefact](https://help.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts); GitHub retains these for 90 days.
+You can download this PDF by clicking on the green check mark beside a commit, then clicking 'details' in the popover; this will navigate to a different page, where you can click on 'Artefacts' and then 'PDF'.
+
+If building the PDF fails, then this is shown by a red cross. 
+This does not necessarily mean that there is a problem with the specification document: automated builds will also fail if they are for a pull request that has already been closed, or are from a different repository (i.e., a fork rather than a branch). 
+
+The action is defined by the file [`.github/workflows/main.yml`](./.github/workflows/main.yml)
+
+## Using LaTeX
+
+### Building the PDF from LateX
 
 To build, run these commands and check the output for errors. If there are errors, resolve them and re-run the failed build step before proceeding.
 
@@ -41,37 +54,3 @@ You can also build with Docker if you don't want to install latex, but note that
     docker run -v $(pwd):/opt/spec jmcl/specbuild
 
 
-# LaTeX installation notes
-
-Installing LaTeX on your system is beyond the scope of this README, however we will collect some tips here, in the interest of fostering collaboration.
-
-
-# MacTex installation notes
-
-Here is how one community member managed to install MacTex and BibTex on OS X 10.10.5 Yosemite in August 2016. This recipe was found on StackOverflow. Not all of these commands may be strictly necessary to build the SBOL2 pdf at this time. The bibdesk settings especially need curation. Please note that BasicTex alone did not suffice.
-
-    # First install homebrew from http://brew.sh then...
-    brew update
-    brew upgrade
-    brew tap caskroom/cask
-    brew install brew-cask
-    brew cask install mactex
-    brew cask install bibtex
-    brew cask install bibdesk
-    brew cask install texshop
-    brew cask install mendeley-desktop
-    sudo chown -R $USER  /usr/local/texlive
-    tlmgr update --self
-    tlmgr update --all
-    defaults write TeXShop NSUserKeyEquivalents -dict-add "Typeset" "@t"
-    defaults write TeXShop "BibTeXengine" -string "biber"
-    defaults write TeXShop "Encoding"  -string  "IsoLatin"
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Cite Key Format" -string %y%u0"
-    defaults write edu.ucsd.cs.mmccrack.bibdesk BDSKLocalFileFormatKey -string Cite Key}%n0%e"
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Path to the papers folder" ing "Biblio"
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Cite String" -string "citep"
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Cite Key Autogenerate" -int 1
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Cite Key Format Preset" -int 0
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Cite Prepend Tilde" -int 1
-    defaults write edu.ucsd.cs.mmccrack.bibdesk "Startup Behavior" -int 4
-

annotation.tex

@@ -0,0 +1,26 @@
+
+\subsection{Annotation and Extension of SBOL}
+\label{sec:Annotations}
+
+SBOL intentionally does not attempt to describe how all types of biological design data should be captured, since many of these data types (e.g., biological context and design performance metrics) are already covered by other standards, or lack a clear consensus on their proper representation, or are outside of the scope of SBOL.
+
+SBOL is built upon the Resource Description Framework (RDF), and therefore can be used in conjunction with complementary standards as described in \ref{sec:complementaryStandards}.  For example, use of the PROV-O ontology is recommended to capture provenance (see \ref{sec:provenance}).  
+Additionally, user-defined RDF can be used in conjunction with SBOL objects to capture custom application-specific information that does not yet have a standardized representation.  
+This annotation and extension mechanism is designed to enable new types of data to be easily incorporated into the SBOL standard once there is community consensus on their proper representation.
+
+Several methods are supported for connecting the SBOL data model with other types of application-specific data:
+
+\begin{itemize}
+\item Custom data can be added to an SBOL object by annotating that object with non-conflicting properties. These properties could contain \sbol{literal} data types such as \sbol{String}s or \sbol{URI}s that require a resolution mechanism to obtain external data. An example is annotating a \sbol{Component} with  a property that contains a \sbol{String} description and \sbol{URI} for the parts registry from which its source data was originally imported.
+\item Custom data in the form of independent objects can participate in the SBOL data model if they are assigned one of the SBOL types \sbol{Identified} or \sbol{TopLevel}.  An example is an RDF object that is annotated such that it represents a data sheet that describes the performance of a \sbol{Component} in a particular context.
+\item Finally, just as custom objects can be embedded in an  SBOL document, external documents can embed or refer to SBOL objects. Support for this last case is not explicitly provided in this specification. Rather, this case depends on the external non-SBOL system managing its relationship to SBOL and data serialized in RDF, and is included here for completeness.
+\end{itemize}
+
+Each \sbol{Identified} object MAY be annotated with application-specific properties, which MUST be labelled using RDF predicates outside of the SBOL namespace.  Additionally, application-specific types may be used in conjunction with the SBOL data model. These application-specific types MUST have two \external{rdf:type} properties: one type outside of the SBOL namespace AND an additional SBOL type of either:
+
+\begin{itemize}
+  \item \sbol{TopLevel}, if the object is to be considered an SBOL top level (i.e., not owned by another object)
+  \item \sbol{Identified}, if the object is not to be considered an SBOL top level (i.e., is owned by another object)
+\end{itemize}
+
+As with SBOL \sbol{Identified} objects, custom \sbol{Identified} objects (and thus also custom \sbol{TopLevel} objects) MAY also include the properties \sbol{displayId}, \sbol{name}, \sbol{description}, etc.