RAML : How to require parameter A OR parameter B

Question

I'm writing some REST documentation with RAML but I'm stuck.

My problem: - I have a GET request used for search that can take a parameter "id" or (exclusive or) "reference". Having only one of them is required.

I know how to say "this param is required" but I don't know how to say "having one of these params is required". Is it even possible?

Answer 1

The following example written in RAML 1.0 defines two object types in Url and File then creates another object Item which requires Url OR File in ext. If you change the included examples (which currently validate), you'll see that they fail if the property does not conform to one or the other definition. Hope that helps! LMK if you have any other questions and I'll do my best.

[EDIT: hmm I think I am seeing your problem now, the final example I've just added, named should_fail, (which has one of each type together in the example) still validates and you want a way to make it fail validation.]

[UPDATE: OK I figured a mildly hacky way to do this. Use maxProperties: 1 in the object which should have properties appear alone, see updated code below which fails the final example during validation.]

#%RAML 1.0
types:
    Url:
        properties:
            url:
                type: string
                example: http://www.cats.com/kittens.jpg
                description: |
                    The url to ingest.

    File:
        properties:
            filename:
                type: string
                example: kittens.jpg
                description: |
                    Name of the file that will be uploaded.


    Item:
        description: |
            An example of a allowing multiple types yet requiring 
            one AND ONLY one of two possible types using RAML 1.0
        properties:
            ext: 
                maxProperties: 1
                type: File | Url
        examples:
            file_example:
                content:
                    ext:
                        filename: video.mp4
            url_example:
                content:
                    ext:
                        url: http://heres.a.url.com/asset.jpg
            should_fail:
                content:
                    ext:
                        url: http://heres.a.url.com/asset.jpg
                        filename: video.mp4