Circular Library References


#1

I am trying to model/design an API using RAML 1.0, and I’m running into a problem with defining domain-types in multiple libraries.

I have a variety of resources which have lots of cross-references which I want to expose in the API. A typical domain library looks like:

#%RAML 1.0 Library
# ObjectA.raml
types:
  Digest:
    type: object
    properties:
      id:
      link: uri
      name:
  Model: 
    type: Digest
    more_data:

This works fine, except when ObjectA.Model contains and array of ObjectB.Digest, and ObjectB.Model contains an array of ObjectA.Digest. Then my two RAML files begin like so:

#%RAML 1.0 Library
# ObjectA.raml
uses:
  ObjectB: !include ObjectB.raml

and

#%RAML 1.0 Library
# ObjectB.raml
uses:
  ObjectA: !include ObjectA.raml

…and API Workbench calls me nasty names for having two libraries include each other.

My feeling is that I can make it go away by combining the libraries, but then I’d lose the namespace separation and the documentation that you get with the uses clause at the top. I could also put the Model and Digests in separate libraries, but then I’d lose having a single file where the closely related types are defined. There must be a better way.

Hopefully, this is a solved problem. Is there another way to reference a datatype that would work?