Input Documentation Unclear

[Arkessler]

Expected Behavior

Documentation at: https://github.com/open-policy-agent/opa/blob/master/docs/content/docs/how-does-opa-work.md should have a more accurate example of a valid input document

Example input document:

{
  "input": {
    "method": "GET",
    "path": "/servers/s2",
    "user": "alice"
  }
}

Actual Behavior

Example input document:

{
  "method": "GET",
  "path": "/servers/s2",
  "user": "alice"
}

As is, the example seems to suggest the "input" key is optional. This is especially misleading when passing input through a json file.

Steps to Reproduce

1. Create a file, input.json, containing:

{
  "method": "GET",
  "path": "/servers/s2",
  "user": "alice"
}

2. Create a policy file, policy.rego, containing;

package input.example

import input

requests[request] {
    request= input[_]
}

3. Load policy into opa and make a document request using --input @input.json
4. Result will not contain expected data

{
    "result": {
        "requests": []
    }
}

[tsandall]

@Arkessler thanks for filing this. I propose we add a paragraph in that section after the example policy that show show you can invoke the policy. For example:

To supply the input document, query OPA using the POST method.

POST /v1/data/example/allow HTTP/1.1
Content-Type: application/json

{
  "input": {
    "method": "GET"
    ...
  }
}

If you'd be able to contribute something like this to the documentation, that would be much appreciated!

[Arkessler]

Will do! Just going to take a bit of time before I can get to it

[artbegolli]

Happy for me to update the Query API docs to clarify this as well?

[tsandall]

Sure, was there a specific part of the Query API section that you had in mind?

…

On Tue, Jun 11, 2019 at 8:22 AM Art Begolli ***@***.***> wrote: Happy for me to update the Query API docs to clarify this as well? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1293?email_source=notifications&email_token=AAB2KJLWITQQKLC2KESSIRLPZ67JTA5CNFSM4HB27JIKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXNP3IY#issuecomment-500891043>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAB2KJMGOGQFQ2EXSAWMPDLPZ67JTANCNFSM4HB27JIA> .

-- -Torin

[artbegolli]

There's an example request under Execute a Simple Query - I've just started experimenting with OPA and feel like the example should include the input document as mentioned here