One document matched: draft-snell-json-test-02.xml

<?xml version="1.0"?> 
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [ 
  <!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
  <!ENTITY rfc4267 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4267.xml'>  
  <!ENTITY rfc3339 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml'>
  <!ENTITY rfc4646 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4646.xml'>
  <!ENTITY rfc4647 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4647.xml'>
  <!ENTITY rfc3987 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3987.xml'>
  <!ENTITY rfc4627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml'>

  <!ENTITY jsonpatch PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-appsawg-json-patch-05.xml'>
]>
<?rfc toc="yes"?> 
<?rfc strict="yes"?> 
<?rfc symrefs="yes" ?> 
<?rfc sortrefs="yes"?> 
<?rfc compact="yes"?> 
<rfc category="info" ipr="trust200811" docName="draft-snell-json-test-02"> 
  <front> 
    <title abbrev="JSON Predicate"> 
      JSON Predicate
    </title> 
 
    <author initials="J.M." surname="Snell" fullname="James M Snell"> 
      <address> 
        <email>jasnell@gmail.com</email> 
      </address> 
    </author> 
    
    <date month="October" year="2012" /> 
 
    <area>Applications</area> 
    <!-- workgroup>Individual Submission</workgroup--> 
    <keyword>I-D</keyword> 
    <keyword>json</keyword>
    <keyword>predicate</keyword>
 
    <abstract> 
      <t>JSON Predicates defines a syntax for serializing various
      predicate expressions as JSON Objects.</t> 
    </abstract> 
 
  </front> 
  
  <middle> 

<section anchor="intro" title="Introduction"> 

  <t>This specification defines JSON Predicates, a JSON-based <xref target="RFC4627"/> 
  syntax for the description and serialization of logical boolean predicate 
  operations intended to be used in conjunction with other JSON-based 
  mechanisms, such as JSON Patch, as a means of incorporating conditional 
  handling during the processing of a JSON document.</t>
  
  <t>JSON Predicates can be used to extend a <xref target="I-D.ietf-appsawg-json-patch">JSON Patch</xref> 
  document to provide for a broader range of conditional processing
  options not currently supported by JSON Patch.</t>
  
  <figure><preamble>Example: Given a source JSON document</preamble>
  <artwork>
  {
    "a": {
      "b": {
        "c": "ABC!XYZ"
      }
    }
  }
  </artwork></figure>
  
  <figure><preamble>The following JSON Patch with JSON Predicates document
  will first test that the value of the "c" property is a string 
  containing the character sequence "ABC" prior to applying the specified
  "replace" operation.</preamble><artwork>
  [
    {
      "op": "and",
      "path": "/a/b",
      "apply": [
        {
          "op": "type", 
          "path": "/c", 
          "value": "string"
        },
        {
          "op": "contains", 
          "path": "/c", 
          "value": "ABC"
        }
      ]
    },
    {
      "op": "replace", 
      "path": "/a/b/c",
      "value": 123
    }
  ]
  </artwork></figure>
  
  <t>It is important to note this specification does not define a 
  distinct JSON Predicates Document format. Rather, it is the intent
  for JSON Predicates to be used within other JSON-based document
  formats, like JSON Patch.</t>

  <t>In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 
  "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 
  are to be  interpreted as described in <xref target="RFC2119" />.</t> 

</section> 

<section anchor="predicates" title="Predicate Objects">

  <t>A JSON Predicate is a JSON Object whose name value
  pairs describe testable conditions that evaluate as either
  true or false.</t>
  
  <t>The essential components of a JSON Predicate include:
  <list style="symbols">
    <t>A label identifying the predicate operation,</t>
    <t>A reference to the value that is to be tested, and </t>
    <t>A condition against which that referenced value is to be evaluated.</t>
  </list>
  </t>

  <t>Predicate objects MUST have exactly one "op" member whose value
  indicates the type of predicate operation to perform. It's value 
  MUST be one of: "and", "contains", "defined", "ends", "in", "less", 
  "matches", "more", "not", "or", "starts", "test", "type", or "undefined". 
  The semantics for each are defined in the sections that follow.</t>  
  
  <t>Note that the value of the "op" member is case-sensitive and that
  each of the operations listed are in lower-case. The value "Starts",
  for example, is not equivalent to "starts".</t>
  
  <t>If the "op" member specifies any value other than one of those 
  listed above, the evaluation of the predicate operation MUST cease
  and be treated as if a boolean value of "false" was returned. The 
  application processing the predicate operation might signal that an 
  error condition has occurred depending on the specific requirements
  of the application within which JSON Predicates are being used.</t>
  
  <t>The remaining structure of each predicate operation depends on it's
  specific type. There are two basic types of predicates.
  <list style="symbols">
    <t>First Order Predicates that are used to test a single
    discreet name value pair against a single condition and</t>
    <t>Second Order Predicates that aggregate one or 
    more subordinate First or Second Order Predicates.</t>
  </list>
  </t>

  <t>In addition to the required "op" member, First Order Predicates 
  have exactly one "path" member whose value MUST be a string 
  containing a JSON-Pointer value referencing the location of the 
  name value pair that is to be tested. If the "path" member is 
  not specified within the predicate object, it's value is assumed
  to be an empty string.</t>
  
  <t>Second Order Predicates MUST have exactly one "apply" member
  whose value is a JSON Array containing one or more First or 
  Second Order Predicate Objects.</t>
  
  <t>Additional members can be required depending on the specific 
  predicate operation. All other members not explicitly defined by
  this specification MUST be ignored.</t>
  
  <t>Note that the ordering of members in JSON objects is not significant;
  therefore the following operations are equivalent:</t>
  
  <figure><artwork>
{"op": "contains", "path": "/a/b/c", "value": "ABC"}
{"path": "/a/b/c", "op": "contains", "value": "ABC"}
{"value": "ABC", "path": "/a/b/c", "op": "contains"}
  </artwork></figure>
  
  <section anchor="context" title="Predicate Context">
    
    <t>All JSON Predicates are evaluated against a given base
    context. The nature of this context is dependent entirely
    on the application within which JSON Predicates is being 
    used. For instance, when used together with JSON Patch, 
    the JSON Predicate operations are evaluated relative to 
    the JSON document that is the target of the JSON Patch
    operation.</t>
      
    <t>Although Predicate Objects use JSON Pointer references
    to identify values against which a predicate operation 
    is evaluated, the base context is not required to be 
    a JSON object or array. In such cases, however, it is 
    the responsibility of the application implementation to 
    determine how to interpret the JSON Pointer reference
    relative to the base context.</t>
    
  </section>
  
  <section anchor="first-order-predicates" title="First Order Predicates">
    
    <section anchor="contains" title="contains">
  
      <t>The "contains" predicate evaluates
      as true if the referenced element is defined and has a value whose 
      string representation contains the exact sequence of characters 
      given by the predicate object's "value" member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": "This is a test"
  }
}
      </artwork></figure>
  
      <figure><preamble>The following predicate would evaluate as 
        "true":</preamble><artwork>
{
  "op": "contains",
  "path": "/a/b", 
  "value": " is a "
}
      </artwork></figure>
    
      <t>By default, character matching MUST be performed in a 
      case-sensitive manner. To override this default behavior, 
      the predicate object MAY contain an "ignore_case" member 
      whose value is either true (to perform case-insensitive
      matching) or false.</t>
    
      <figure><preamble>For instance, the following will evaluate 
      as "true":</preamble><artwork>
{
  "op": "contains",
  "path": "/a/b/", 
  "value": " Is A ", 
  "ignore_case": true
}
      </artwork></figure>

    </section>
  
    <section anchor="defined" title="defined">
      
      <t>The "defined" predicate evaluates
      as true if the referenced element exists within the 
      target context.</t>
      
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
"a": {
  "b": null
 }
}
      </artwork></figure>
      
      <figure><preamble>The following predicate would evaluate as
        "true" because the path "/a/b" 
        exist within the document despite being explicitly set to
        null:</preamble><artwork>
{
  "op": "defined",
  "path": "/a/b"
}
      </artwork></figure>
      
      <figure><preamble>The following predicate would 
        evaluate as "false" because
        the path "/a/c" does exist within the document.</preamble><artwork>
{
  "op": "defined",
  "path": "/a/c"
}
      </artwork></figure>
      
    </section>
  
    <section anchor="ends" title="ends">
    
      <t>The "ends" predicate evaluates
      as true if the referenced element is defined and has a value whose 
      string representation ends with the exact sequence of characters 
      given by the predicate object's "value" 
      member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": "This is a test"
  }
}
      </artwork></figure>
  
      <figure><preamble>The following predicate would evaluate as 
        "true":</preamble><artwork>
{
  "op": "ends",
  "path": "/a/b", 
  "value": " test"
}
      </artwork></figure>
    
      <t>By default, character matching MUST be performed in a 
      case-sensitive manner. To override this default behavior, 
      the predicate object MAY contain an "ignore_case" member 
      whose value is either "true" (to perform case-insensitive
      matching) or false.</t>

      <figure><preamble>For instance, the following will evaluate as 
        "true":</preamble><artwork>
{
  "op": "ends",
  "path": "/a/b/", 
  "value": " TEST", 
  "ignore_case": true
}
      </artwork></figure> 
    
    </section>
      
    <section anchor="in" title="in">
      
      <t>The "in" predicate evaluates as true if the referenced element 
        specifies a value exactly equal to one of the members of a JSON
        array provided by the predicate's "value" member. Equality is 
        determined following the sames rules specified for the JSON 
        Patch "test" operation in <xref target="I-D.ietf-appsawg-json-patch"/>, Section 4.6,
        with one exception given for optional case-insensitive comparisons.</t>
      
        <figure><preamble>For example, given the JSON document:</preamble>
        <artwork>
  {
    "a": {
      "b": 10
    }
  }
        </artwork></figure>
    
        <figure><preamble>The following will evaluate as 
          "true":</preamble><artwork>
  {
    "op": "in",
    "path": "/a/b", 
    "value": [1, "foo", 10, {"z":"y"}]
  }
        </artwork></figure>
        
        <t>The value specified for the "value" member MUST be a JSON Array.</t>
        
        <t>By default, when comparing string values, character matching 
        MUST be performed in a case-sensitive manner. To override this default 
        behavior, the predicate object MAY contain an "ignore_case" member 
        whose value is either "true" (to perform case-insensitive
        matching) or false.</t>
      
    </section>
      
    <section anchor="less" title="less">
    
      <t>The "less" predicate evaluates
      as true if the referenced element is defined and specifies a number 
      whose value is less than that specified by the predicate object's 
      "value" member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": 10
  }
}
      </artwork></figure>
    
      <figure><preamble>The following will evaluate as 
        "true":</preamble><artwork>
{
  "op": "less",
  "path": "/a/b", 
  "value": 15
}
      </artwork></figure>
    
    </section>

    <section anchor="matches" title="matches">
    
      <t>The "matches" predicate evaluates
      as true if the referenced element is defined and has a value whose 
      completely string representation matches the regular expression 
      provided by the predicate object's "value" member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": "this is a test"
  }
}
      </artwork></figure>
    
      <figure><preamble>The following evalutes as 
        "true":</preamble><artwork>
{
  "op": "matches",
  "path": "/a/b", 
  "value": "[\\w\\s]*"
}
      </artwork></figure>
    
      <t>The predicate's matching pattern is expressed as a string 
      value conforming to the JavaScript Regular Expression syntax.</t> 
    
      <t>By default, character matching MUST be performed in a 
      case-sensitive manner. To override this default behavior, 
      the predicate object MAY contain an "ignore_case" member 
      whose value is either "true" (to perform case-insensitive
      matching) or false. Setting the value of "ignore_case" to 
      true is equivalent to using the "i" modifier flag within 
      the JavaScript Regular Expression syntax (e.g. "/\w\s/*/i").</t>
    
      <figure><preamble>For instance:</preamble><artwork>
{
  "op": "ends", 
  "path": "/a/b/", 
  "value": "[\\w\\s]*", 
  "ignore_case": true
}
      </artwork></figure> 
    
    </section>
    
    <section anchor="more" title="more">
    
      <t>The "more" predicate evaluates
      as true if the referenced element is defined and specifies a number 
      whose value is greater than that specified by the predicate object's 
      "value" member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": 10
  }
}
      </artwork></figure>
    
      <figure><preamble>The following will evaluate as 
        "true":</preamble><artwork>
{
  "op": "more",
  "path": "/a/b", 
  "value": 5
}
      </artwork></figure>
    
    </section>

    <section anchor="starts" title="starts">
    
      <t>The "starts" predicate evaluates
      as true if the referenced element is defined and has a value whose 
      string representation begins with the exact sequence of characters 
      given by the predicate object's "value" member.</t>
    
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
  "a": {
    "b": "This is a test"
  }
}
      </artwork></figure>
  
      <figure><preamble>The following predicate would evaluate as 
        "true":</preamble><artwork>
{
  "op": "starts",
  "path": "/a/b", 
  "value": "This "
}
      </artwork></figure>
    
      <t>By default, character matching MUST be performed in a 
      case-sensitive manner. To override this default behavior, 
      the predicate object MAY contain an "ignore_case" member 
      whose value is either "true" (to perform case-insensitive
      matching) or false.</t>
    
      <figure><preamble>For instance, the following will evaluate as "true":</preamble><artwork>
{
  "op": "starts",
  "path": "/a/b/", 
  "value": "this ", 
  "ignore_case": true
}
      </artwork></figure> 
    
    </section>
    
    <section anchor="test" title="test">
      
      <t>The JSON Patch "test" operation, as defined by <xref target="I-D.ietf-appsawg-json-patch" />, Section 4.6,
      can be used as a First Order Predicate operation. It evaluates as true if the referenced
      element exists and specifies a value that is exactly equal to that provided
      by the predicate's "value" member. The rules for evaluating equality are identical
      to those defined within <xref target="I-D.ietf-appsawg-json-patch"/>, Section 4.6,
      with one exception given for optional case-insensitive comparisons.</t>
      
      <figure><preamble>For example, given the JSON document:</preamble><artwork>
{
  "a": {
    "b": "this is a test"
  }
}
      </artwork></figure>
      
      <figure><preamble>The following predicate would evaluate as 
        "true"</preamble><artwork>
{
  "op": "test",
  "path": "/a/b", 
  "value": "this is a test"
}
      </artwork></figure>
      
      <t>By default, when comparing string values, character matching 
      MUST be performed in a case-sensitive manner. To override this default 
      behavior, the predicate object MAY contain an "ignore_case" member 
      whose value is either "true" (to perform case-insensitive
      matching) or false.</t>
      
    </section>
    
    <section anchor="type" title="type">
    
      <t>The "type" predicate 
      evaluates as true if the referenced element exists and specifies 
      a value whose value type is equal to that specified by the predicate's 
      "value" member.</t>
    
      <t>The "value" member MUST specify one of: "number",
      "string", "boolean", "object", "array", "null", 
      "undefined", "date", "date-time", "time", "lang", "lang-range", 
      "iri" or "absolute-iri".</t>
    
      <figure><preamble>For example, given the JSON document:</preamble><artwork>
{
  "a": {
    "b": "this is a test",
    "c": [1,2,3]
  }
}
      </artwork></figure>
    
      <figure><preamble>The following predicate would evaluate as 
        "true"</preamble><artwork>
{
  "op": "type",
  "path": "/a/b", 
  "value": "string"
}
      </artwork></figure>
      
      <t>When evaluating the type of a value, the following rules apply:
        <list style="symbols">
          <t>If the "value" member specifies "number", the type predicate
            will evaluate as true if the value referenced by the "path" 
            member is a JSON number.</t>
          <t>If the "value" member specifies "string", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string.</t>
          <t>If the "value" member specifies "boolean", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON boolean.</t>
          <t>If the "value" member specifies "object", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON object.</t>
          <t>If the "value" member specifies "array", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON array.</t>
          <t>If the "value" member specifies "null", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON null.</t>
          <t>If the "value" member specifies "undefined", the type predicate
            will evaluate as true if the member referenced by the "path"
            member does not exist.</t>
          <t>If the "value" member specifies "date", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string conforming to the <xref target="RFC3339"/>
            "full-date" construct.</t>
          <t>If the "value" member specifies "time", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string conforming to the <xref target="RFC3339"/>
            "full-time" construct.</t>
          <t>If the "value" member specifies "date-time", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string conforming to the <xref target="RFC3339"/>
            "date-time" construct.</t>
          <t>If the "value" member specifies "lang", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string conforming to the <xref target="RFC4646"/>
            "Language-Tag" construct.</t>
          <t>If the "value" member specifies "lang-range", the type predicate
            will evaluate as true if the value referenced by the "path"
            member is a JSON string conforming to the <xref target="RFC4647"/>
            "language-range" construct.</t>
          <t>If the "value" member specifies "iri", the type predicate will
            evaluate as true if the value referenced by the "path" member
            is a JSON string conforming to the <xref target="RFC3987"/>
            "IRI-reference" construct.</t>
          <t>If the "value" member specifies "absolute-iri", the type predicate
            will evaluate a true if the value referenced by the "path" member
            is a JSON string conforming to the <xref target="RFC3987"/>
            "IRI" construct.</t>
        </list>
      </t>
    </section>
    
    <section anchor="undefined" title="undefined">
      
      <t>The "undefined" predicate evaluates
      as true if the referenced element does not exist within the 
      target context.</t>
      
      <figure><preamble>For example, given the JSON document:</preamble>
      <artwork>
{
"a": {
  "b": null
 }
}
      </artwork></figure>
      
      <figure><preamble>The following predicate would evaluate as
        "true" because the path "/a/c" 
        does not exist within the document:</preamble><artwork>
{
  "op": "undefined",
  "path": "/a/c"
}
      </artwork></figure>
      
      <figure><preamble>However, the following predicate would 
        evaluate as "false" because
        the path "/a/b" does exist within the document, despite
        specifying an explicit null value.</preamble><artwork>
{
  "op": "undefined",
  "path": "/a/b"
}
      </artwork></figure>
      
    </section>

    
  </section>

  <section anchor="second-order-predicates" title="Second-Order Predicates">
        
    <t>Second Order Predicates are defined as sets of one or more
    subordinate First and Second Order Predicates.</t>
    
    <t>All Second Order Predicates MAY contain a "path" member whose 
    value specifies a root path prefix for all contained predicates.
    If the "path" member is not specified, it's value is assumed to 
    be an empty string. For example, given the JSON document:</t>
    
    <figure><artwork>
{
  "a": {
    "b": {
      "c": "ABC!"
    }
  }
}
    </artwork></figure>
    
    <figure><preamble>The following would evaluate as true because the path
    "/a/b/c" is defined.</preamble><artwork>
{
  "op": "and",
  "path": "/a/b",
  "apply": [
    {
      "op": "defined", 
      "path": "/c"
    }
  ]
}
    </artwork></figure>
    
    <figure><preamble>The above example is equivalent to:</preamble><artwork>
    {
      "op": "and",
      "apply": [
        {
          "op": "defined", 
          "path": "/a/b/c"
        }
      ]
    }
    </artwork></figure>

    <section anchor="and" title="and">
    
      <t>The "and" predicate evaluates as 
      "true" if all of it's contained set 
      of predicate operations evaluate as "true".</t>

      <figure><preamble>For example, given the JSON document:</preamble><artwork>
{
  "a" : {
    "b" : "foo",
    "c" : {
      "d": 10
    }
  }
}
      </artwork></figure>
    
      <figure><preamble>The following would evaluate as "true" 
      because the element "/a/b" is defined and the value of element "/a/c/d" is less than 
      15.</preamble><artwork>
{
  "op": "and",
  "apply" [
    {
      "op": "defined", 
      "path": "/a/b"
    },
    {
      "op": "less",
      "path": "/a/c/d", 
      "value": 15
    }
  ]
}
      </artwork></figure>
    
      <figure><preamble>However, the following would evaluate as 
      "false" because while the element "/a/c" exists, the value 
      of that element is not a string.</preamble><artwork>
{
  "op": "and",
  "apply": [
    {
      "op": "test",
      "path": "/a/c"
    },
    {
      "op": "type",
      "path": "/a/c", 
      "value": "string"
    }
  ]
}
      </artwork></figure>
    
    </section>

    <section anchor="not" title="not">
    
      <t>The "not" predicate evaluates as 
      "true" if all of it's contained set of predicate 
      operations evaluate as "false".</t>
    
      <figure><preamble>For example, given the JSON document:</preamble><artwork>
{
  "a" : {
    "b" : "foo",
    "c" : {
      "d": 10
    }
  }
}
      </artwork></figure>
    
      <figure><preamble>The following would evaluate as "true" 
      because the element "/a/b/e" is undefined and the value of element "/a/c/d" is 
      not less than 5.</preamble><artwork>
{
  "op": "not",
  "apply": [
    {
      "op": "defined", 
      "path": "/a/b/e"
    },
    {
      "op": "less", 
      "path": "/a/c/d", 
      "value": 5
    }
  ]
}
      </artwork></figure>
    
      <figure><preamble>However, the following would evaluate as 
        "false" because the element "/a/c"
        exists and the value for element "/a/b" begins with the letter
        "f"</preamble><artwork>
{
  "op": "not",
  "apply": [
    {
      "op": "undefined", 
      "path": "/a/c"
    },
    {
      "op": "starts", 
      "path": "/a/b", 
      "value": "f"
    }
  ]
}
      </artwork></figure>    
    </section>
  
    <section anchor="or" title="or">

      <t>The "or" predicate evaluates as 
      "true" if at least one of it's contained 
      set of predicate operations evaluate as "true".</t>

      <figure><preamble>For example, given the JSON 
        document:</preamble><artwork>
{
  "a" : {
    "b" : "foo",
    "c" : {
      "d": 10
    }
  }
}
      </artwork></figure>
    
      <figure><preamble>The following would evaluate as "true" 
      because the element "/a/b" is defined.</preamble><artwork>
{
  "op": "or",
  "apply": [
    {
      "op": "defined",
      "path": "/a/b"
    },
    {
      "op": "less",
      "path": "/a/c/d", 
      "value": 5
    }
  ]
}
      </artwork></figure>
    
      <figure><preamble>However, the following would evaluate as 
        "false" because neither elements "/a/e" or "/a/f" exist.</preamble><artwork>
{
  "op": "or",
  "apply": [
    {
      "op": "test",
      "path": "/a/e"
    },
    {
      "op": "test",
      "path": "/a/f"
    }
  ]
}
      </artwork></figure>   

    </section>
  
    <section title="Nesting Second Order Predicates">
    
      <t>Second Order Predicates can be combined in a variety 
      of ways to define more complex test operations. For example:</t>
    
      <figure><artwork>
{
  "op": "or",
  "path": "/a/b",
  "apply": [
    {
      "op": "not",
      "path": "/c",
      "apply": [
        {"op": "undefined"},
        {"op": "starts", "value": "f"}
      ]
    },
    {
      "op": "not",
      "path": "/d",
      "apply": [
        {"op": "defined"},
        {"op": "type", "value": "number"}
      ]
    }
  ]
}
      </artwork></figure>
    
    </section>
  
  </section>
      
  <section anchor="error-handling" title="Error Handling">
    
    <t>When an error condition is encounted during the processing of a
    JSON Predicate, the predicate MUST evaluate as false. Whether or not
    the error condition is reported is dependent on the specific requirements
    of the application within which JSON Predicates are being used.</t>
    
    <t>Error conditions can arise in each of the following conditions:
      <list style="symbols">
        <t>JSON Predicate Objects contained within a document fail to 
          conform to any normative requirement of this specification, or</t>
        <t>The Predicate Object specifies an unknown predicate operation, or</t>
        <t>The Predicate Object specifies a JSON Pointer referencing 
        a value that does not exist and the specified Predicate operation 
        is not specifically intended to test for the absence of a value 
        (i.e. the "undefined" and "defined" predicates), or</t>
        <t>A First Order Predicate Object specifies a predicate operation
        that requires a "value" member providing the condition to test but 
        no "value" member is provided.</t>
        <t>The "value" member given for a given predicate operation is of
          an unexpected or unsupported type for that operation (e.g.
          specifying a string value for the "more" and "less" predicate
          operations).</t>
      </list>
    </t>
    
  </section>
  
  <section anchor="json-patch" title="Using JSON Predicate within JSON Patch Documents">
    
    <t>While JSON Predicate objects can be used in a variety of applications, 
    the syntax has been specifically designed for compatibility with the 
    JSON Patch Document format. JSON Predicate objects MAY be used directly
    within a JSON Patch Document as tests to evaluate whether or not the 
    application of a set of patch operations should succeed or fail.</t>
    
    <t>Because of requirements defined by the JSON Patch specification, 
    when Second Order Predicates are used as patch test operations within 
    a JSON Patch document, the "path" member MUST be specified. The value 
    of the "path" member MAY be an empty string.</t>
    
    <figure><preamble>For example, given the following JSON document:</preamble>
    <artwork>
{
  "a": {
    "b": {
      "c": "123"
    }
  }
}
    </artwork></figure>
    
    <figure><preamble>The following JSON Patch + JSON Predicates document will 
      first test that the path "/a/b/c" references a string value matching the 
      given regular expression prior to replacing that value:</preamble><artwork>
[
  {
    "op": "and",
    "path": "/a/b/c",
    "apply": [
      {"op": "type", "value": "string"},
      {"op": "matches", "value": "\\d{3}"}
    ]
  },
  {
    "op": "replace",
    "path": "/a/b/c",
    "value": "ABC"
  }
]
    </artwork></figure>
    
    <t>When a JSON Predicate object within a JSON Patch document evaluates as 
    false, processing of the JSON Patch Document MUST be handled exactly the 
    same as an unsuccessful JSON Patch operation would be handled as defined 
    in <xref target="I-D.ietf-appsawg-json-patch">JSON-PATCH</xref>, Section 5. 
    Specifically, processing of the JSON Patch document SHOULD terminate and 
    application of the entire patch document SHALL NOT be deemed successful.</t>
    
    <t>An implementation SHOULD make consumers of JSON Patch documents aware that 
    predicate objects are included by appending the optional parameter 
    "predicates=1" to the "application/patch+json" MIME media type.</t>
  
    <t>For example:</t>
    
    <figure><artwork>
  PATCH /some-document HTTP/1.1
  Host: example.org
  Content-Type: application/patch+json; predicates=1
  
  [
    {
      "op": "matches",
      "path": "/a/b/c",
      "value": "\\d{3}"
    },
    {
      "op": "replace",
      "path": "/a/b/c",
      "value": "ABC"
    }
  ] 
    </artwork></figure>
    
    <t>JSON Patch implementations that do not implement or recognize
    JSON Predicate objects will treat them as unknown patch operations 
    that will cause evaluation of the Patch document to fail.</t>
    
  </section>
  
</section>
      
<section title="IANA Considerations">
  
  <t>This specification introduces an additional optional "predicates" 
    parameter to the "application/patch+json" MIME Media Type. The value
    of the predicates parameter MUST be "1". The presence of "predicates=1"
    as a parameter of the "application/patch+json" media type is an 
    explicit indication that the JSON Patch document contains JSON
    Predicate objects.</t>
    
</section>
      
<section title="Security Considerations">
<t>JSON Predicate objects do not, by themselves, introduce any particular 
  security concerns. Note that JSON documents that consist of an arbitrary
  number of nested Second Order Predicate objects can have a detrimental 
  impact on overall performance and could be leveraged by a malicious 
  entity as part of a denial of service attack.</t>
</section>

</middle> 
<back>
<references title="Normative References"> 
  &rfc2119;
  &rfc3987;
  &rfc4647;
  &rfc4646;
  &rfc4627;
  &rfc3339;
</references>
<references title="Informative References">
  &jsonpatch;
</references>
</back>
</rfc>