1# Copyright (c) 2015 Sandstorm Development Group, Inc. and contributors
2# Licensed under the MIT License:
3#
4# Permission is hereby granted, free of charge, to any person obtaining a copy
5# of this software and associated documentation files (the "Software"), to deal
6# in the Software without restriction, including without limitation the rights
7# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8# copies of the Software, and to permit persons to whom the Software is
9# furnished to do so, subject to the following conditions:
10#
11# The above copyright notice and this permission notice shall be included in
12# all copies or substantial portions of the Software.
13#
14# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20# THE SOFTWARE.
21
22@0x8ef99297a43a5e34;
23
24$import "/capnp/c++.capnp".namespace("capnp::json");
25
26struct Value {
27  union {
28    null @0 :Void;
29    boolean @1 :Bool;
30    number @2 :Float64;
31    string @3 :Text;
32    array @4 :List(Value);
33    object @5 :List(Field);
34    # Standard JSON values.
35
36    call @6 :Call;
37    # Non-standard: A "function call", applying a named function (named by a single identifier)
38    # to a parameter list. Examples:
39    #
40    #     BinData(0, "Zm9vCg==")
41    #     ISODate("2015-04-15T08:44:50.218Z")
42    #
43    # Mongo DB users will recognize the above as exactly the syntax Mongo uses to represent BSON
44    # "binary" and "date" types in text, since JSON has no analog of these. This is basically the
45    # reason this extension exists. We do NOT recommend using `call` unless you specifically need
46    # to be compatible with some silly format that uses this syntax.
47  }
48
49  struct Field {
50    name @0 :Text;
51    value @1 :Value;
52  }
53
54  struct Call {
55    function @0 :Text;
56    params @1 :List(Value);
57  }
58}
59
60# ========================================================================================
61# Annotations to control parsing. Typical usage:
62#
63#     using Json = import "/capnp/compat/json.capnp";
64#
65# And then later on:
66#
67#     myField @0 :Text $Json.name("my_field");
68
69annotation name @0xfa5b1fd61c2e7c3d (field, enumerant, method, group, union) :Text;
70# Define an alternative name to use when encoding the given item in JSON. This can be used, for
71# example, to use snake_case names where needed, even though Cap'n Proto uses strictly camelCase.
72#
73# (However, because JSON is derived from JavaScript, you *should* use camelCase names when
74# defining JSON-based APIs. But, when supporting a pre-existing API you may not have a choice.)
75
76annotation flatten @0x82d3e852af0336bf (field, group, union) :FlattenOptions;
77# Specifies that an aggregate field should be flattened into its parent.
78#
79# In order to flatten a member of a union, the union (or, for an anonymous union, the parent
80# struct type) must have the $jsonDiscriminator annotation.
81#
82# TODO(someday): Maybe support "flattening" a List(Value.Field) as a way to support unknown JSON
83#   fields?
84
85struct FlattenOptions {
86  prefix @0 :Text = "";
87  # Optional: Adds the given prefix to flattened field names.
88}
89
90annotation discriminator @0xcfa794e8d19a0162 (struct, union) :DiscriminatorOptions;
91# Specifies that a union's variant will be decided not by which fields are present, but instead
92# by a special discriminator field. The value of the discriminator field is a string naming which
93# variant is active. This allows the members of the union to have the $jsonFlatten annotation, or
94# to all have the same name.
95
96struct DiscriminatorOptions {
97  name @0 :Text;
98  # The name of the discriminator field. Defaults to matching the name of the union.
99
100  valueName @1 :Text;
101  # If non-null, specifies that the union's value shall have the given field name, rather than the
102  # value's name. In this case the union's variant can only be determined by looking at the
103  # discriminant field, not by inspecting which value field is present.
104  #
105  # It is an error to use `valueName` while also declaring some variants as $flatten.
106}
107
108annotation base64 @0xd7d879450a253e4b (field) :Void;
109# Place on a field of type `Data` to indicate that its JSON representation is a Base64 string.
110
111annotation hex @0xf061e22f0ae5c7b5 (field) :Void;
112# Place on a field of type `Data` to indicate that its JSON representation is a hex string.
113
114annotation notification @0xa0a054dea32fd98c (method) :Void;
115# Indicates that this method is a JSON-RPC "notification", meaning it expects no response.
116