Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Easy Data Modeling with MSON (Defrag 2016)

paraskakis
November 16, 2016

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.

paraskakis

November 16, 2016
Tweet

More Decks by paraskakis

Other Decks in Programming

Transcript

  1. OBSERVATION #1 
 APIs ARE MOSTLY DATA Apiary users spend

    a lot of time thinking about modeling data
  2. OBSERVATION #2 
 SOFTWARE PRODUCTS ARE MOSTLY DATA In my

    product career, I’ve spent a lot of time modeling data
  3. 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
  4. BUT THEY ALL HAVE TO AGREE ON A PRECISE DEFINITION

    or their needs will not be met, 
 API projects will fail
  5. 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
  6. 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
  7. A TASK - JSON SCHEMA { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object",

    "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }
  8. 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" ]
  9. PRIMITIVE TYPES - id: 42 (number, required) - Uniquely identifies

    task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
  10. NAMED TYPES # Task - id: 42 (number, required) -

    Uniquely identifies task - title: Buy Milk (string, nullable) - Task title - complete: false (boolean) - Completion Status
  11. STRUCTURE TYPES - id: 84 (number, required) - Uniquely identifies

    project - name: Shopping List (string, nullable) - Name of project - tasks (array[Task])
  12. STRUCTURE TYPES { "id": 84, "name": "Shopping List", "tasks": [

    { "id": 42, "title": "Buy Milk", "complete": false } ] }
  13. 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" ] }
  14. INHERITANCE # User - id: 1 (number, required) - Uniquely

    identifies user - name: Emmanuel Paraskakis (string, required) - Name of user - email: [email protected] (string, required) - User email # TeamMember (User) - team: Shoppers (required) - Team name - role: Dairy (nullable) - Role name
  15. apiary.io • Collaboration • Documentation • Prototype (Mock) • Console

    • →JSON • →JSON Schema • Inspector • Automated Tests
  16. 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
  17. 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: [email protected] (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