Easy Data Modeling with MSON (Defrag 2016)

A lot of time is spent on data modeling in software projects. But no data modeling language exists that's accessible to business stakeholders, technical users as well as machines. We propose Markdown Syntax for Object Notation as a solution. MSON has been a runaway success for people describing data models within API Descriptions in the last year on Apiary.
Presented at Defrag 2016 in Denver.

Transcript

1. EASY DATA MODELING WITH MSON Emmanuel Paraskakis (@manp) VP of Product, Apiary
4. OBSERVATION #1 
 APIs ARE MOSTLY DATA Apiary users spend a lot of time thinking about modeling data
5. OBSERVATION #2 
 SOFTWARE PRODUCTS ARE MOSTLY DATA In my product career, I’ve spent a lot of time modeling data
6. WHERE DO DATA MODELS COME FROM? • DBAs, Devs: SQL/ORM schemas • Architects: ER diagrams and the like • Business users: spreadsheets/documents • API devs: API definitions, JSON Schema • Front-end folks: Core Data, GraphQL schemas
7. CAN YOU SEE THE PROBLEM? 
 same needs; different languages
8. BUT THEY ALL HAVE TO AGREE ON A PRECISE DEFINITION or their needs will not be met, 
 API projects will fail
9. ALL STAKEHOLDERS NEED A COMMON LANGUAGE: • Accessible to techies and business people • Usable by machines • Broad and articulate enough to
 describe most data models • Independent of implementation
 (defer architecture decisions) • DRY - duh
10. WE HAVE A SOLUTION! 
 Markdown Syntax
 for Object Notation (MSON)
11. https://github.com/apiaryio/mson • Based on Markdown - not a `{` to be seen • Parsable, Open Source Spec • Broad enough:
 Used by Apiary users this past year (7%) • Converts to JSON Schema (we’re in the API biz) …anything else you’d like in the future! • Encourages reuse
12. A TASK - JSON { "id": "42", "title": "Buy Milk" }
13. A TASK - JSON SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }
14. A TASK - MSON - id: 42 - title: Buy Milk
15. MARKDOWN • id: 42 • title: Buy Milk
16. SPEC 1. Values 2. Descriptions 3. Types 4. Inheritance
17. VALUES - id: 42 - title: Buy Milk
18. DESCRIPTIONS - id: 42 - Uniquely identifies task - title: Buy Milk - Task title
19. PRIMITIVE TYPES { "id": 42, "title": "Buy Milk", "complete": false } numeric required can be null a boolean
20. PRIMITIVE TYPES { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id": { "type": "number", "description": "Uniquely identifies task" }, "title": { "type": [ "string", "null" ], "description": "Task title" }, "complete": { "type": "boolean", "description": "Completion Status" } }, "required": [ "id" ]
21. PRIMITIVE TYPES - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
22. NAMED TYPES # Task - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
23. STRUCTURE TYPES - id: 84 (number, required) - Uniquely identifies project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task])
24. STRUCTURE TYPES { "id": 84, "name": "Shopping List", "tasks": [ { "id": 42, "title": "Buy Milk", "complete": false } ] }
25. STRUCTURE TYPES { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "id": { "type": "number", "description": "Uniquely identifies project" }, "name": { "type": [ "string", "null" ], "description": "Name of project" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Uniquely identifies task" }, "title": { "type": [ "string", "null" ], "description": "Task title" }, "complete": { "type": "boolean", "description": "Completion Status" } }, "required": [ "id" ] } } }, "required": [ "id" ] }
26. INHERITANCE # User - id: 1 (number, required) - Uniquely identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: emmanuel@apiary.io (string, required) - User email # TeamMember (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name
27. INHERITANCE { "id": 1, "name": "Emmanuel Paraskakis", "email": "emmanuel@apiary.io", "team": "Shoppers", "role": "Dairy" }
28. apiary.io • Collaboration • Documentation • Prototype (Mock) • Console • →JSON • →JSON Schema • Inspector • Automated Tests
29. THANK YOU! • MSON OSS spec/parsers - please contribute! • Can be read/written by all - collaboration • Focus on getting semantics right • Format-independent • Try MSON today on apiary.io
30. apiary.io emmanuel@apiary.io @manp QUESTIONS?
31. FORMAT: 1A HOST: http://polls.apiblueprint.org/ # Project Management API Demo API for MSON Conference talk. Basic Project Management including tasks and team members ## Tasks [/tasks] A task can have a team member assigned to it. It can also be complete or incomplete ### List all [GET] - Response 200 (application/json) - Attributes (array[Task], fixed-type) ## Task [/tasks/{id}] ### Retrieve a Task [GET] - Response 200 (application/json) - Attributes (Task) ## Projects [/projects] A project is a named collection of tasks ### List all [GET] + Response 200 (application/json) - Attributes (array[Project], fixed-type) ## Project [/projects/{id}] ### Retrieve a Project [GET] + Response 200 (application/json) - Attributes (Project) ## TeamMember [/teammembers] A Team Member inherits from a User ### List all [GET] + Response 200 (application/json) - Attributes (array[TeamMember], fixed-type) ## TeamMember [/teammembers/{id}] - Attributes (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name ### Retrieve a TeamMember [GET] + Response 200 (application/json) - Attributes (TeamMember) # Data Structures ## User - id: 1 (number, required) - Uniquely identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: emmanuel@apiary.io (string, required) - User email ## Task - id: 42 (number, required) - Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status - teamMemberId: 1 (number) - Must exist as a Team Member ## Project - id: 84 (number, required) - Uniquely identifies project - name: Shopping List (string, nullable) - Name of project SAMPLE API BLUEPRINT (68 LINES) http://docs.defragmsondemo.apiary.io https://github.com/EmmanuelDefrag/msondemo