Powerful IDE for API-first design, documentation and development.

Start my Free Trial

There are situations where you'll want a message to reference an object by its ID, similar to the idea of a foreign key in a database. 


RAPID-ML data models use references, not foreign keys, to link data objects. But RAPID-ML data structures can have properties that serve as IDs, and you can structure messages to use these IDs as foreign keys to objects managed in external systems. 


Example


Here's a model illustrating referenceEmbeds for key properties:


/* 
  This is the TaxBlaster API model created in the RepreZen Quick Start guide.
*/
rapidModel TaxBlaster

  resourceAPI TaxBlasterInterface baseURI "http://taxblaster.com/api"
    objectResource TaxFilingSummary type TaxFiling
      URI /taxfiling/{id}/summary
        required templateParam id bound to property filingID

      referenceEmbed > taxpayer
        targetProperties
          taxpayerID
          employer
        referenceEmbed > employer
          targetProperties
            companyID

      method GET getTaxFilingSummary
        request
        response TaxFilingSummary statusCode 200

  /** Supporting data types for the TaxBlaster API */
  dataModel TaxBlasterDataModel
    structure TaxFiling
      filingID : string
      taxpayer : reference to Taxpayer
      jurisdiction : string
      year : gYear
      period : int
      currency : string
      grossIncome : decimal
      taxLiability : decimal

    structure Taxpayer
      taxpayerID : string
      lastName : string
      firstName : string
      otherNames : string*
      dob : date
      employer : reference to Company
      
    structure Company
      companyID : string
      companyName : string
      netRevenue : decimal
      currency : string


In the TaxFilingSummary, this is the realization that embeds the IDs of related objects:


      referenceEmbed > taxpayer
        targetProperties
          taxpayerID
          employer
        referenceEmbed > employer
          targetProperties
            companyID


Notice how the referenceEmbeds can be nested recursively.  


Here's a JSON Schema, generated from this model, and modified to put the realization at the top level:


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Schema for TaxBlaster model",
  "title": "TaxBlaster",
  "type": "object",
  "properties": {
    "filingID": {
      "type": "string"
    },
    "jurisdiction": {
      "type": "string"
    },
    "year": {
      "type": "string"
    },
    "period": {
      "type": "integer"
    },
    "currency": {
      "type": "string"
    },
    "grossIncome": {
      "type": "number"
    },
    "taxLiability": {
      "type": "number"
    },
    "taxpayer": {
      "$ref": "#/definitions/TaxFilingSummary_taxpayer"
    }
  },
  "definitions": {
    "TaxFilingSummary": {
      "type": "object",
      "minProperties": 1,
      "properties": {
        "filingID": {
          "type": "string"
        },
        "jurisdiction": {
          "type": "string"
        },
        "year": {
          "type": "string"
        },
        "period": {
          "type": "integer"
        },
        "currency": {
          "type": "string"
        },
        "grossIncome": {
          "type": "number"
        },
        "taxLiability": {
          "type": "number"
        },
        "taxpayer": {
          "$ref": "#/definitions/TaxFilingSummary_taxpayer"
        }
      }
    },
    "TaxFilingSummary_taxpayer": {
      "type": "object",
      "minProperties": 1,
      "properties": {
        "taxpayerID": {
          "type": "string"
        },
        "employer": {
          "$ref": "#/definitions/TaxFilingSummary_taxpayer_employer"
        }
      }
    },
    "TaxFilingSummary_taxpayer_employer": {
      "type": "object",
      "minProperties": 1,
      "properties": {
        "companyID": {
          "type": "string"
        }
      }
    }
  }
}


And here's a JSON object that conforms to this schema:


{
  "filingID" : "1234",
  "jurisdiction" : "US/Federal",
  "year" : "2015",
  "period" : 0,
  "currency" : "USD",
  "grossIncome" : 82853,
  "taxLiability" : 2150,
  "taxpayer" : {
    "taxpayerID" : "999-99-9999",
    "employer" : {
      "employerID" : "C987234"
    }
  }
}


We can describe this structure as follows::

  • The root object is a TaxFiling with an embedded taxpayer object (whose type is Person).  
  • The taxpayer has only a taxpayerID, and an embedded employer object (whose type is Company).  
  • The employer object has only the employerID.