Using the OpenAPI Spec to validate JSON requests  

First, it would be awesome if Apigee had a built in policy to validate requests against an OAS, like for XSDs, but currently it’s not available. It would be even more awesome, if only one validation policy was required, since the OAS already has all the definitions.

Even though it’s not built in, we can get SO CLOSE with just one simple Javascript policy using tv4, and the OAS. It relies on the fact that the OAS "operationId" === proxy "current.flow.name" on conditional flows.

The OAS fragment

...
"paths": {
        "/nodes": {
            "post": {
                "operationId": "createNode",
                "parameters": [{
                    "name": "node",
                    "in": "body",
                    "required": true,
                    "schema": {
                        "$ref": "#/definitions/NodeCreateRequest"
                    }
                }],  
...    

Create a Javascript policy to validate the requests using the OAS as an included resource.

1. Create the oas.js resource and JSON object by simply pasting the entire JSON spec into oas.js and assigning it to a variable (e.g. var oas = { ...spec... }; ).
2. Add the tv4-min.js resource, just copy and paste.

The JS-ValidateRequest Policy

<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JS-ValidateRequest">
    <DisplayName>JS-ValidateRequest</DisplayName>
    <Properties/>
    <IncludeURL>jsc://oas.js</IncludeURL>
    <IncludeURL>jsc://tv4-min.js</IncludeURL>
    <ResourceURL>jsc://ValidateRequest.js</ResourceURL>
</Javascript>

The ValidateRequest.js script is pretty straight forward

1. Get the schema for the operationId from the OAS .
2. Load the OAS schema into tv4
3. Validate the request
4. If validation fails set “javascript.errorMessage” variable and throw an error triggering a “ScriptExecutionFailed” fault.
5. In fault rules, you can differentiate from other script errors by checking the policy name that failed. (e.g. javascript.JS-ValidateRequest.failed === true).

try {
    var verb = context.getVariable('request.verb');
    var pathsuffix = context.getVariable('proxy.pathsuffix');
    var flowname = context.getVariable('current.flow.name');
    var schema = getMessageSchema( flowname );

    if( schema === undefined || schema === null ) {
        throw "Missing schema definition for: " + verb + " " + pathsuffix;
    }
    else {
        var bodyContent = context.getVariable('request.content');
        var body = JSON.parse(bodyContent);
        
        tv4.addSchema('/schema', oas);
        
        var result = tv4.validateMultiple(body, schema);
    
        // A missing schema validates to true, but we want that to be an error
        // Override missing entry with full schema value
        if( result.missing[0] ) {
            result.errors[0] = {"schema":schema};
            throw "Schema definition not found" + JSON.stringify(result.errors);
        }
        else if( result.valid === false ) {
            throw "Validation failed for: " + verb + " " + pathsuffix + ": " + JSON.stringify(result.errors);
        }
    }
}
catch( err ) {
    // This raises fault named "ScriptExecutionFailed", 
    // and sets errorMessage to the validation result
    context.setVariable('javascript.errorMessage', err);
    throw err;
}

function getMessageSchema( flowname ) {
    // Find the operationId that matches the flowname
    // Return the schema from the parameter that is "in" "body"
    // More efficient than using jsonPath
    var paths = oas.paths;
    for ( var path in paths ) {
        var verbs = paths[path];
        for( var verb in verbs ) {
            if( verbs[verb].operationId === flowname ) {
                var params = verbs[verb].parameters;
                for ( var param in params ) {
                    if( params[param].hasOwnProperty( 'in' ) && params[param].in === 'body' ) {
                        return params[param].schema;
                    }
                }
            }
        }
    }
    return undefined;
}

SO CLOSE: As you can see, we almost have a “standard” policy. All we need is access to the OAS! We know that when a proxy is created using an OAS, the spec is referenced via the association.js resource, but that’s just a link to the spec, not the entire spec. AFAIK, there is no way to access the full spec at runtime. If there was, we wouldn’t have to copy and paste the OAS into a resource file.

Even so, this single Javascript policy can now be placed on any conditional flow where validation needs to be performed.

See the attached proxy and Postman collection.