D-Factor: How Strong Is Your Data Contract?

D-Factor:
How strong is your data contract?
TED EPSTEIN, FOUNDER & CEO
MODELSOLV, INC.
COPYRIGHT © 2014, MODELSOLV, INC. | ALL RIGHTS RESERVED. 1

D-Factor: Data Contract Capabilities
Inspired by Mike Amundsen’s H Factor:
◦ http://amundsen.com/hypermedia/hfactor/
H-Factor describes hypermedia capabilities of a media type.
D-Factor describes characteristics or capabilities of a
Data Description Scheme.
◦ Data Description Scheme: the means by which your API defines and
communicates a data contract to the client developer and/or client software.
◦ Data Contract: metadata that specifies the format, structure, constraints and
semantics of data included in a request or response message

Data Contract Styles
Lots of different ways to specify a data contract:
◦ Schema
◦ Profile
◦ Media Type
◦ Link Relation
Emphasis: Static vs. Dynamic
Is “stronger” always better?

Foundational Factors

MSD
SDC
DS
MR
TI
OWA
SRA
SC
DS: Domain-Specificity
The foundation of all other D-factors.
Domain-neutral messages conform only to a
format, not a meaningful model.
Domain-specific messages tell the client
what to expect, and what meaning may be
ascribed to the message.

MSD
SDC
DS MR
TI
OWA
SRA
SC
SC: Standardization Context
Universal
Geopolitical
Sector/Industry
Organization
Private
SC

MSD
SDC
DS MR
TI
OWA
SRA
SC
MR: Machine Readability
Contract is expressed in some machine-readable
form:
◦ JSON Schema
◦ XML Schema
◦ .proto File
◦ Avro Schema
MR

MSD
SDC
DS MR
TI
OWA
SRA
SC
TI: Technology-Independence
◦ Microformats / Profiles
◦ ALPS, Schema.org, Dublin Core
◦ Description Language
◦ Apiary/MSON, RepreZen
◦ Modeling Language
◦ UML, ERD, ECore, OWL
TI

Static Description Factors

MSD
SDC
SDC
DS MR
TI
OWA
SRA
SC
SDC: Static Data Contract
The data contract is specified as part of your
API specification.
Client developers know that data matching
this description is expected to occur
somewhere.
… but not necessarily where.

MSD
SDC
SRA
DS MR
TI
OWA
SRA
SC
SRA: Static Resource Association
In a specific context, the client can expect to
retrieve a resource having a specific kind of data.
A static resource association may be established by:
◦ Media type description: The resource may be reached
through a hyperlink from another resource, whose media
type specifies that the target resource will be in a specific
form (or media type)
◦ Link Relation
◦ Human-readable documentation
NOTE: strict REST is not supposed to have
“resource types.”

Dynamic Description Factors

MSD
MSD
SDC
DS MR
TI
OWA
SRA
SC
MSD: Message Self-Description
Message includes the data contract, or a link to
it, in some form.
Is just specifying the media type or link relation
enough?
◦ Yes, if the media type or link relation specifies a
domain-specific data contract.
Three different levels:
◦ Domain-specific data contract specified in media type or link
relation.
◦ Data contract linked from message
◦ Data contract included in the message

MSD
SDC
OWA
DS MR
TI
OWA
SRA
SC
OWA: Open World Assumption
Allow out-of-schema elements
Allow schema extensions
◦ type derivation
◦ substitution groups

Not Covered
Human Readability
Message-based validation capability
Data Modeling Features
◦ Primitive Types
◦ Explicit null values
◦ Generalization / Specialization / Inheritance(single or multiple) / Classification
(single or multiple) / Extension / Restriction / Mixins / Traits / Prototypes /
Templates / Generics…
... and other forms of reuse.

Suggestions?

D-Factor: How Strong Is Your Data Contract?

More Related Content

Similar to D-Factor: How Strong Is Your Data Contract?

Recently uploaded

D-Factor: How Strong Is Your Data Contract?