Quick Introduction on OSLC APIs For Digital Engineering Information Exchange (DEIX) Community explaining fundamental ideas behind OSLC including:
- Distributed Link Creation Strategy from within ANY application
- Link creation decoupled from link persistence/analysis/visualization
- Embeddable search dialogs to support user-friendly link target discovery in any application
- Standardized API discovery resources (Hypermedia API)
Structural Analysis and Design of Foundations: A Comprehensive Handbook for S...
Introduction to Open Services for Lifecycle Collaboration (OSLC)
1. Open Services for Lifecycle
Collaboration (OSLC)
Quick Introduction on OSLC APIs
For Digital Engineering Information Exchange
(DEIX) Community
Axel Reichwein
June 11, 2021
1
2. Axel Reichwein
2
● PhD in aerospace engineering at University of
Stuttgart + Postdoc at GeorgiaTech
● Previously involved in SysML standardization efforts
(SysML-Modelica + SysML v2 API)
● Created Koneksys in 2012 to offer MBSE/SysML
consulting services and offer software consulting
services for data integration using Open Services
for Lifecycle Collaboration (OSLC)
● Member of the OASIS OSLC Open Project Governing
Board since 2017
● Co-Organizer of the OSLCFest
3. PhD and postdoc focused on
tradeoff studies
Reconfiguring architecture
model to then automatically
sync detailed discipline-specific
models
Applying rule-based design in
engineering
Centralized Link Creation
Strategy
Until 2012: Focus on using data standards
3
4. Using Web APIs
Using widely adopted open
standards like HTTP, URLs, and RDF
Data integration inspired by the
World Wide Web
Distributed Link Creation
Strategy
Since 2012: Focus on using API standards
4
5. Highly Heterogeneous Engineering Data
5
Disciplines
Software
Applications
(> 500 apps)
Data
(syntax and
semantics)
and API/SDK
Engineering
Diversity
6. Crosscutting Concerns across Eng Disciplines
6
Requirements
Engineering
Design Manufacturing Operation
Traceability
Configuration
management
Change
Management
Reuse
8. Knowing exactly how a requirement has
been tested (vs believing what is written in
a document)
Knowing what is impacted if something
changes
Knowing when having to run again
simulation models
Knowing how to run simulation models in
the right sequence with the right
parameters
Benefits of Connected Engineering Data
8
Connected Engineering Data is more meaningful than siloed Engineering Data
9. Each linked artifact needs to have a unique
global/universal identifier (e.g. URL)
Each link has a type so that we understand
the meaning of the relationship
Each link has a direction from source to target
What is a Link?
9
https://rm.koneksys.com
/api/oslc/project1/require
ment/FAA23.155
https://rm.koneksys
.com/api/oslc/projec
t1/testcase/23.155
Link Source
Identifier
Link Target
Identifier
Link Type
Identifier
http://open-ser
vices.net/ns/rm
#:validatedBy
validatedBy
10. Requiring data-ingestion into a “central” data
store, thus many data transformations
between schemas (which change over time)
Data ingestion often performed batch-wise
(No guarantee of having latest up-to-date
data)
Technology changes -> Choice of central
data store will change over time (e.g. data
lake instead of PLM for IoT data)
Links only created within one software
application (e.g. specific PLM, MBSE app)
Traditional Centralized Link Creation Strategy
10
Until now, this approach has not
proven to be scalable
“Central” Data
Store (e.g. PLM)
11. Suitable for exchanging data
between applications within
the same domain with a
clearly defined scope
Successful Schemas for Data
Exchange/Interoperability
11
STEP AP242
FMI
ReqIF
12. The larger the domain scope...
● the more likely the schema needs to be
updated to stay relevant,
● the harder it is for implementations of
the schema to support all its concepts
and to stay up-to-date with schema
changes
● the less likely the schema will be
adopted,
● and the less likely the schema will
provide value
Individual Schemas covering multiple
domains...
12
Multi-domain schemas getting bigger and
bigger...
“Central” Data
Store (e.g. PLM)
Schema of
“Central” Data
Store (e.g. PLM)
13. Links are created from within ANY
application. All applications are equal from a
linking perspective
Links created only as needed by engineers
within their familiar applications
(user-friendly!)
Central registry for linking rules to ensure that
only meaningful links of a certain type are
used between artifacts of a certain type
Multiple smaller (and more manageable)
domain-specific schemas defined in the
same format (RDF) are used instead of one
multidomain monolithic schema
Distributed Link Creation Strategy
13
Central Registry for
Linking Rules
14. Links can be persisted in multiple storage
solutions at time of creation
Data and Links are accessible to API
clients and can be collected and saved in
another storage solution for
● Query purposes
● Visualization
● Analysis
● Triggering automated workflows
Multiple Link Storage & Analysis &
Visualization Options
14
PLM SysML
Graph
database
Data Lake
Link Management not constrained to the
capabilities of a single application
Link Creation and Link Storage
should be decoupled
15. Distributed Link Creation Strategy
15
User selects an
artifact as a link
source
Requirements App
Link Editor can find
available link targets in other
data sources
Req 123 User selects an
artifact as a link
target
Link Editor
Test Cases
Simulation
Models
3D Models/PLM SysML Models
16. Distributed Link Creation Strategy
16
User selects an
artifact as a link
source
Test Cases App
Test 123 User selects an
artifact as a link
target
Link Editor
Requirements
Simulation
Models
3D Models/PLM SysML Models
Any software application can have a link
editor. Applications of link sources and link
targets need to be interchangeable!
17. REST APIs
17
Test Cases App
Test 123 Link Editor
Requirements
Simulation
Models
3D Models/PLM SysML Models
Most software applications
already have a REST API or will
have one soon!
REST API REST API REST API REST API
18. The Five API Styles: Understanding REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka - by Erik Wilde
Youtube video: https://www.youtube.com/watch?v=bWFXGHXo_pY
Different API Styles
18
API Style Popular API Technology
Tunnel gRPC
Resource REST
Hypermedia REST + representation format which can
describe links/controls
Query GraphQL
Event Kafka
REST style is advantageous for
linking as it exposes data as
uniquely identifiable
resources (objects)
19. Example HTTP GET Request
19
Data
API
API Client
HTTP GET
Request
https://rm.koneksys.co
m/api2/rest/project1/re
quirement/FAA23.65
{
"identifier": "FAA23.65",
"title": "FAA 23.65 Climb: All Engines Operating.",
"description": "The climb tests associated with ...",
"about": "https://.../project1/requirement/FAA23.65"
}
REST API Characteristics:
● Database/Application agnostic
● Access to objects of any granularity
200 OK
20. Adding a link to an API resource...
20
Data
API
API Client
HTTP PUT
Request
https://rm.koneksys.co
m/api2/rest/project1/re
quirement/FAA23.65
{
"identifier": "FAA23.65",
"title": "FAA 23.65 Climb: All Engines Operating.",
"description": "The climb tests associated with ...",
"about": "https://.../project1/requirement/FAA23.65"
“validatedBy”: "https://.../projectX/testcase/123"
}
??
Assumption: URL of linked test case is
already known
21. ...Most REST APIs Adopt the Closed World
Assumption
21
Data
API
API Client
HTTP PUT
Request
{
"identifier": "FAA23.65",
"title": "FAA 23.65 Climb: All Engines Operating.",
"description": "The climb tests associated with ...",
"about": "https://.../project1/requirement/FAA23.65"
“validatedBy”: "https://.../projectX/testcase/123"
}
400 Bad
Request
Updates to REST API resources only valid if
updates conform to expected changes
(e.g. modifications to a set of predefined
properties)
CWA: what is not
currently known to be
true, is false (or only
what is known to be
true, is true)
OWA: what is not
currently known to be
true may be true (or
only what is known to be
false, is false)
22. Most REST APIs reflect the Closed World nature
of their applications. REST APIs cannot
anticipate all the link types used to connect
API resources
Purpose of REST APIs is to expose data of an
application, not to support linking of API
resources
Central registry for linking rules for preventing
random updates to API resources
Link Types Independent of REST APIs
22
Central Registry for
Linking Rules
REST API REST API
REST API REST API
Link
Type
#1 Link Type
#2
Link Type #3
Link Type #4
Link
Type
#5
A link-enabling API following the Open World
Assumption is needed to support linking of
API resources with any link types
23. OSLC APIs Can Adopt the Open World
Assumption
23
Data
API
API Client
HTTP PUT
Request
@prefix ...
<https://.../api/oslc/project1/requirement/FAA23.65>
a oslc_rm:Requirement ;
dc:description "The climb tests associated ..." ;
dc:identifier "FAA23.65" ;
dcterms:title "FAA 23.65 Climb: All Engines... ";
oslc_rm:validatedBy "https://.../.../testcase/123"
Update of an REST API resource to include a
new property will be valid if compliant with
linking rules
200 OK
25. Link Target Discovery
25
User selects an
artifact as a link
source
Test Cases App
Test 123 User selects an
artifact as a link
target
Link Editor
Requirements
Simulation
Models
3D Models/PLM SysML Models
Each software application has different
search mechanisms to find a specific object
in its database/model
28. Application-specific Search Dialog
28
Data
API
API Client
HTTP GET
Request
https://rm.koneksys.co
m/api/oslc/project1/req
uirement/selector
200 OK
Application-specific search dialogs
can be embedded in other
applications as HTML Iframe
29. Discovery of the
Search Dialog URL
29
Test Cases App
Test 123 Link Editor
Requirements
Simulation
Models
3D Models/PLM SysML Models
Each software application
exposes its OSLC search dialog
at a different URL
https://urlX
https://urlY https://urlZ
30. Hypermedia To Discover Web Page URL
30
What is the URL of the Web page describing a specific
NBA game? As a user, I know the main entry point
Web page (e.g. https://www.espn.com/)
I also know the category of the game (e.g. NBA)
And then I can find the specific game and its URL (e.g.
https://www.espn.com/nba/game?gameId=40126763
6)
Entry Point
List of data containers
Resources of a specific
type within a container
URL of specific resource
31. Hypermedia To Discover API Resource URL
31
All OSLC APIs support the discovery
of resources exposed by the API
according to:
● Data container
● Version of data container
● Resource type
● Sometimes delegated search
dialogs
http://api2.com/serviceprovidercatalo
g
http://api2.com/serviceproviders
http://api2.com/model1/parameters
http://api2.com/model1/parameters/12
Entry Point
List of data containers
Resources of a specific
type within a container
URL of specific resource
33. Discovering Link Targets Through
Standardized OSLC API Resources
33
Target Data
Provider #1
Target Data
Provider #2
OSLC API
OSLC API
Link Editor
(OSLC API
Client)
Source Data
Provider
35. Unique Global Identifiers
35
● Linked resources need to have unique global identifiers
● Unique global identifiers can also be used to access the resources (e.g. HTTP URLs)
● Links have a type identified by unique global identifiers
3
5
https://www.api1.exam
ple.com/projectA/requ
irements/123
https://www.api2.exam
ple.com/projectB/testc
ases/456
http://open-services.n
et/ns/rm#validatedBy
Requirement 123 TestCase 456
Link
36. Resource With Outgoing Links
36
Requirement 123 TestCase 456
https://www.api1.example.com/pro
jectA/requirements/123
https://www.api2.example.com/pr
ojectB/testcases/456
http://open-services.net/ns/rm#
validatedBy
Requirement
Change Request X
Defect Y
http://myvocab.net/fixes
http://open-services.
net/ns/qm#relatedC
hangeRequest
https://www.api3.example.com/pr
ojectX/changerequests/X
https://www.api4.example.com/pr
ojectX/defects/Y
37. RDF as Graph Data Model
37
Requirement 123 TestCase 456
Requirement
Change Request X
Defect Y
URL of link source URL of link type URL of link target
https://.../requirements/123 http://...validatedBy https://...testcases/456
https://.../requirements/123 http://...fixes https://...defects/Y
https://.../requirements/123 http://...relatedChangeRequest https://...changerequests/X
38. RDF can be described in many formats
38
URL of link source URL of link type URL of link target
https://.../requirements/123 http://...validatedBy https://...testcases/456
https://.../requirements/123 http://...fixes https://...defects/Y
https://.../requirements/123 http://...relatedChangeRequest https://...changerequests/X
XML JSON Turtle RDFa
40. Accessing Resources as HTTP API Client
40
Requirement 123 TestCase 456
Requirement
Change Request X
Defect Y
API
Client
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:ns1="http://myvocab.net/"
xmlns:ns2="http://open-services.net/ns/rm#"
xmlns:ns3="http://open-services.net/ns/qm#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns
#"
>
<rdf:Description
rdf:about="https://www.api1.example.com/projectA/req
uirements/123">
<ns2:validatedBy
rdf:resource="https://www.api2.example.com/projectB/t
estcases/456"/>
<ns1:fixes
rdf:resource="https://www.api4.example.com/projectX/
defects/Y"/>
<ns3:relatedChangeRequest
rdf:resource="https://www.api3.example.com/projectX/
changerequests/X"/>
</rdf:Description>
</rdf:RDF>
HTTP GET
RDF
https://www.api1.example.com/pro
jectA/requirements/123
41. Schemas defined in RDF: Schema.org
41
4
1
Search engines
understand
content in Web
pages
Web pages
in HTML
containing
RDF
RDF Vocabulary
Interoperability between search
engines and Web content
42. RDF vocabulary:
- A vocabulary is set of URLs that identifies resource types
and resource properties that belong to a specific
Namespace for a domain application.
● Vocabulary for Requirement Management
● Vocabulary for Global Configuration Management
● Vocabulary for OSLC Core
Constraints:
- To define well formedness rules (e.g. a requirement can
only have one identifier property). Defined by python
classes with closed namespaces taken from the
specifications.
Schema in RDF Applying OWA =
RDF Vocabulary + Constraints
42
Data
API
API Client
Requirement 123
Title: …
Description:...
HTTP GET
Request
43. Namespace URI for OSLC Requirements Management (RM) vocabulary is:
http://open-services.net/ns/rm#
URL of the Requirement resource type (RDFS Class):
http://open-services.net/ns/rm#Requirement
Example RDF Vocabulary for Requirements
43
URL of Requirement
Properties
Multiplicity
Constraints
Description
dcterms:identifier Exactly-one An identifier for a resource. This identifier may be unique with a scope
that is defined by the RM provider. Assigned by the service provider
when a resource is created. Not intended for end-user display.
oslc_rm:affectedBy Zero-or-many The subject is affected by the object, such as a defect or issue.
oslc_rm:constrainedBy Zero-or-many The subject is constrained by the object. For example, a functional
requirement is constrained by a safety requirement.
oslc_rm:elaboratedBy Zero-or-many The subject is elaborated by the object. For example, a user
requirement is elaborated by use case.
45. Covered Domains
● Architecture Management
● Asset Management
● Automation
● Change Management
● Performance Monitoring
● Quality Management
● Reconciliation
● Requirements Management
● Existing specs can be easily extended (e.g. to
represent requirements with custom properties)
● Existing domain-specific specs likely to evolve over
time
● Specs should ideally be aligned with
domain-specific standards such as ReqIF, SysML, or
STEP defined by traditional standardization
organizations. It is easy to convert an existing
OMG/STEP standard into an equivalent
Web-compatible OSLC specification
● Many non-official domain-specific OSLC
specifications have been created by developers of
OSLC APIs to describe domains related to simulation
(e.g. FMI) and MBSE.
45
Existing OSLC Domain-Specific Specifications
50. 50
Configurations Exposed by OSLC APIs
Data
API #1
API Client
Client can discover
available
configurations from
the different OSLC
APIs
Configurations
Link Store
Data
API #2
Configurations
51. 51
Change Events Exposed by OSLC APIs
Data
API #1
API Client
Client can
pull the
change
events from
the different
OSLC APIs
Change Events
Link Store
Data
API #2
Change Events
52. 52
Access Rules Exposed by OSLC APIs
Data
API #1
API Client
Client can
retrieve the
access rules
from the
different
OSLC APIs
Access rules
Link Store
Data
API #2
Access Rules
54. OSLC Adoption
54
Vendor Application
IBM IBM Jazz Applications (e.g. DNG)
Lifecycle Query Engine
Global Configuration Management
Jazz Reporting Service
Mentor Context
Sodius SECollab
MID Smartfacts
PTC Integrity Modeler
pure-sys
tems
pure::variants
PROSTEP OpenPDM
● Check out videos of the OSLCFest
● Active open-source community
● OSLC adoption growing slowly but
steadily
● Total of approx. 50 OSLC APIs for
different engineering applications
● No support from established software
vendors who fear losing vendor
lock-in
● OSLC documentation needs to be
improved (e.g. with more examples)
● Lack of awareness of OSLC in
academia, Semantic Web and graph
database communities
5
4
55. Eclipse Lyo (Java-based SDK to create OSLC APIs)
PyOSLC (Python-based SDK to create OSLC APIs)
Soon to be released by Koneksys: Auto-generated OSLC API as wrapper on top of existing REST
API based on OpenAPI extensions
Getting Started with OSLC
55
Data
API
Data
REST API
OSLC API
OSLC API
OSLC Deployment Option #1 OSLC
Deployment
Option #2
58. ● Distributed Link Creation Strategy from within ANY application
● Link creation decoupled from link persistence/analysis/visualization
● Embeddable search dialogs to support user-friendly link target discovery in any
application
● Standardized API discovery resources (Hypermedia API)
● API exposing Data & Links
● Unique global identifiers for describing data, schemas, and link types
● Domain-specific schemas defined in a common data format using unique global
identifiers
Technology-Independent Linking Principles
58
59. Old
● Single “central” application to define
links
● Data accessible as files
● Data having to be transformed into a
neutral “central” data format before
being linked
● Links described in a vendor-specific
format
● Links can only be accessed,
managed, analysed, visualized within
a single “central” application
New
● Any application can define links
● Data directly accessible as API
resources (“objects”) at any level of
granularity
● Data is linked by linking API resources
(simple HTTP PUT operation to update
an API resource representation)
● Links described in neutral open format
● Decoupling of concerns: Links can be
accessed, managed, analysed,
visualized in different applications
59
Data Integration: Old vs New (OSLC)
60. Open Services for Lifecycle Collaboration
Standard for Link-enabling APIs
● Based on Linked Data principles
● REST API
● Supporting resource and service
discovery
● Generic data aspects and API
discovery aspects described in a
standard way
● Easily consumable by knowledge
graphs
60
Schemas for Generic Data Aspects
● API entry point and services
● Containers of resources
● Shapes (and constraints) of resources
● Versions of resources
● Change events on resources
● Resource access rules