[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.0

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.0

Jordan, Bret
All,

After several weeks of an open comment period and having received lots of good feedback and comments from a large number of you - who knew JSON would be so popular - and then working though several issues I now formally submit this document for inclusion in the official record.   

I will update my Golang APIs to support these final changes in the coming days.  




Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 


TAXII_JSON_Message_Binding_Specification_v1.00.pdf (304K) Download Attachment
signature.asc (858 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.0

Terry MacDonald
Great work Bret!

Cheers
Terry MacDonald


On 15 April 2015 at 06:01, Jordan, Bret <[hidden email]> wrote:
All,

After several weeks of an open comment period and having received lots of good feedback and comments from a large number of you - who knew JSON would be so popular - and then working though several issues I now formally submit this document for inclusion in the official record.   

I will update my Golang APIs to support these final changes in the coming days.  




Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 



Reply | Threaded
Open this post in threaded view
|

[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

Jordan, Bret
In reply to this post by Jordan, Bret
I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  

While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.





Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 

On Apr 14, 2015, at 2:02 PM, Bret Jordan <[hidden email]> wrote:

All,

After several weeks of an open comment period and having received lots of good feedback and comments from a large number of you - who knew JSON would be so popular - and then working though several issues I now formally submit this document for inclusion in the official record.   

I will update my Golang APIs to support these final changes in the coming days.  

<TAXII_JSON_Message_Binding_Specification_v1.00.pdf>


Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 



TAXII_JSON_Message_Binding_Specification_v1.01.pdf (304K) Download Attachment
signature.asc (858 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

mdavidson

Bret,

 

I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.

 

Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.

Section 1.3, message_id should be represented using the Courier New font

 

Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.

 

Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”

- Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.

- The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON

 

Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).

- These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.

- Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not

- You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3

 

In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.

 

I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.

 

In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?

 

In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.

 

In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)

 

In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.

 

Table 3.5-1

- collection_information_response very nearly runs off the table

- This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.

- I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”

 

Table 3.6-1 – The subscription_management_request is visually truncated by the table

Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document

 

Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column

 

Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?

 

Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?

 

As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.

 

Thank you.

-Mark

 

 

From: Jordan, Bret [mailto:[hidden email]]
Sent: Tuesday, April 14, 2015 10:49 PM
To: taxii-discussion-list Trusted Automated Exchange of Indicator In
Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

 

I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  

 

While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.

 

 

Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

Jordan, Bret
Thanks for the feedback, I will work on this tomorrow night

Bret 

Sent from my Commodore 64

On Apr 15, 2015, at 7:05 AM, Davidson II, Mark S <[hidden email]> wrote:

Bret,

 

I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.

 

Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.

Section 1.3, message_id should be represented using the Courier New font

 

Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.

 

Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”

- Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.

- The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON

 

Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).

- These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.

- Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not

- You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3

 

In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.

 

I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.

 

In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?

 

In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.

 

In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)

 

In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.

 

Table 3.5-1

- collection_information_response very nearly runs off the table

- This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.

- I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”

 

Table 3.6-1 – The subscription_management_request is visually truncated by the table

Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document

 

Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column

 

Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?

 

Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?

 

As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.

 

Thank you.

-Mark

 

 

From: Jordan, Bret [[hidden email]]
Sent: Tuesday, April 14, 2015 10:49 PM
To: taxii-discussion-list Trusted Automated Exchange of Indicator In
Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

 

I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  

 

While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.

 

 

Reply | Threaded
Open this post in threaded view
|

[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.02

Jordan, Bret
In reply to this post by mdavidson
Mark, et all, 

I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.




Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 

On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:

Bret,
 
I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.
 
Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
Section 1.3, message_id should be represented using the Courier New font
 
Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.
 
Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
- Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
- The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON
 
Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects). 
- These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
- Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
- You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3
 
In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.
 
I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.
 
In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?
 
In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.
 
In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)
 
In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.
 
Table 3.5-1
- collection_information_response very nearly runs off the table
- This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
- I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”
 
Table 3.6-1 – The subscription_management_request is visually truncated by the table
Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document
 
Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column
 
Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?
 
Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?
 
As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.
 
Thank you.
-Mark
 
 
From: Jordan, Bret [[hidden email]] 
Sent: Tuesday, April 14, 2015 10:49 PM
To: taxii-discussion-list Trusted Automated Exchange of Indicator In
Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01
 
I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  
 
While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.


TAXII_JSON_Message_Binding_Specification_v1.02.pdf (311K) Download Attachment
signature.asc (858 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.02

Sergey Polzunov
Bret,

I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas

I noticed few things in this version of the spec:

-  Table 3.1-3 inconsistencies:
        - “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
        - SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.

- “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).

- How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..

- “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.

- Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas

Thanks,
Sergey Polzunov
Intelworks


> On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:
>
> Mark, et all,
>
> I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.
>
> <TAXII_JSON_Message_Binding_Specification_v1.02.pdf>
>
>
> Thanks,
>
> Bret
>
>
>
> Bret Jordan CISSP
> Director of Security Architecture and Standards | Office of the CTO
> Blue Coat Systems
> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>
>> On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:
>>
>> Bret,
>>  
>> I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.
>>  
>> Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
>> Section 1.3, message_id should be represented using the Courier New font
>>  
>> Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.
>>  
>> Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
>> - Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
>> - The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON
>>  
>> Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
>> - These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
>> - Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
>> - You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3
>>  
>> In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.
>>  
>> I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.
>>  
>> In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?
>>  
>> In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.
>>  
>> In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)
>>  
>> In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.
>>  
>> Table 3.5-1
>> - collection_information_response very nearly runs off the table
>> - This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
>> - I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”
>>  
>> Table 3.6-1 – The subscription_management_request is visually truncated by the table
>> Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document
>>  
>> Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column
>>  
>> Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?
>>  
>> Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?
>>  
>> As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.
>>  
>> Thank you.
>> -Mark
>>  
>>  
>> From: Jordan, Bret [mailto:[hidden email]]
>> Sent: Tuesday, April 14, 2015 10:49 PM
>> To: taxii-discussion-list Trusted Automated Exchange of Indicator In
>> Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01
>>  
>> I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  
>>  
>> While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.
>

Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.02

Jordan, Bret
Great catches and thanks for pointing them out.  I will get them fixed tonight/tomorrow and send out an update.

Bret

Sent from my Commodore 64

> On May 10, 2015, at 10:18 AM, Sergey Polzunov <[hidden email]> wrote:
>
> Bret,
>
> I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas
>
> I noticed few things in this version of the spec:
>
> -  Table 3.1-3 inconsistencies:
>    - “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
>    - SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.
>
> - “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).
>
> - How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..
>
> - “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.
>
> - Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas
>
> Thanks,
> Sergey Polzunov
> Intelworks
>
>
>> On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:
>>
>> Mark, et all,
>>
>> I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.
>>
>> <TAXII_JSON_Message_Binding_Specification_v1.02.pdf>
>>
>>
>> Thanks,
>>
>> Bret
>>
>>
>>
>> Bret Jordan CISSP
>> Director of Security Architecture and Standards | Office of the CTO
>> Blue Coat Systems
>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>
>>> On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:
>>>
>>> Bret,
>>>
>>> I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.
>>>
>>> Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
>>> Section 1.3, message_id should be represented using the Courier New font
>>>
>>> Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.
>>>
>>> Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
>>> - Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
>>> - The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON
>>>
>>> Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
>>> - These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
>>> - Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
>>> - You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3
>>>
>>> In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.
>>>
>>> I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.
>>>
>>> In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?
>>>
>>> In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.
>>>
>>> In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)
>>>
>>> In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.
>>>
>>> Table 3.5-1
>>> - collection_information_response very nearly runs off the table
>>> - This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
>>> - I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”
>>>
>>> Table 3.6-1 – The subscription_management_request is visually truncated by the table
>>> Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document
>>>
>>> Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column
>>>
>>> Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?
>>>
>>> Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?
>>>
>>> As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.
>>>
>>> Thank you.
>>> -Mark
>>>
>>>
>>> From: Jordan, Bret [mailto:[hidden email]]
>>> Sent: Tuesday, April 14, 2015 10:49 PM
>>> To: taxii-discussion-list Trusted Automated Exchange of Indicator In
>>> Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01
>>>
>>> I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  
>>>
>>> While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.
>
Reply | Threaded
Open this post in threaded view
|

[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.03

Jordan, Bret
In reply to this post by Sergey Polzunov
Once again, thanks for finding those issues, here is an updated version with with your changes, v1.03.  I have also updated the APIs at https://github.com/jordan2175/freetaxii to reflect these changes so everything should work correctly. 


Change Log

1) Table 3.1-3 has been updated so that SUPPORTED_BINDINGS is now called SUPPORTED_ENCODINGS to match the rest of the document.

2) In Table 3.1-3 SUPPORTED_CONTENTS was removed since it is not used in the JSON spec anywhere

3) In Table 3.6-1 “push_parameters" was renamed to “delivery_parameters" to better match the specification and give consistency with Table 3.8-1

4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different

5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.

6) In Table 3.5-1 I renamed “polling_services” to be “poll_services” to match all of the user uses of just “poll” in the document.  

7) Updated the examples to reflect the changes above.

8) Updated the Bibliography. 

Once again, thanks for the careful read and all of the good suggestions.  

Thanks,

Bret





Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 

On May 10, 2015, at 10:18 AM, Sergey Polzunov <[hidden email]> wrote:

Bret,

I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas

I noticed few things in this version of the spec:

-  Table 3.1-3 inconsistencies:
- “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
- SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.

- “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).

- How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..

- “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.

- Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas

Thanks,
Sergey Polzunov
Intelworks


On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:

Mark, et all,

I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.

<TAXII_JSON_Message_Binding_Specification_v1.02.pdf>


Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."

On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:

Bret,

I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.

Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
Section 1.3, message_id should be represented using the Courier New font

Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.

Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
- Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
- The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON

Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
- These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
- Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
- You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3

In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.

I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.

In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?

In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.

In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)

In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.

Table 3.5-1
- collection_information_response very nearly runs off the table
- This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
- I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”

Table 3.6-1 – The subscription_management_request is visually truncated by the table
Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document

Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column

Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?

Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?

As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.

Thank you.
-Mark


From: Jordan, Bret [[hidden email]]
Sent: Tuesday, April 14, 2015 10:49 PM
To: taxii-discussion-list Trusted Automated Exchange of Indicator In
Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  

While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.




TAXII_JSON_Message_Binding_Specification_v1.03.pdf (309K) Download Attachment
signature.asc (858 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

[TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.04

Jordan, Bret
I had to back one change out,

> 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.

And now I remember why I did not do it in the first place, as it will mess up the data structure for the the Subscription Request message.



Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 

On May 11, 2015, at 2:19 PM, Bret Jordan <[hidden email]> wrote:

Once again, thanks for finding those issues, here is an updated version with with your changes, v1.03.  I have also updated the APIs at https://github.com/jordan2175/freetaxii to reflect these changes so everything should work correctly. 


Change Log

1) Table 3.1-3 has been updated so that SUPPORTED_BINDINGS is now called SUPPORTED_ENCODINGS to match the rest of the document.

2) In Table 3.1-3 SUPPORTED_CONTENTS was removed since it is not used in the JSON spec anywhere

3) In Table 3.6-1 “push_parameters" was renamed to “delivery_parameters" to better match the specification and give consistency with Table 3.8-1

4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different

5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.

6) In Table 3.5-1 I renamed “polling_services” to be “poll_services” to match all of the user uses of just “poll” in the document.  

7) Updated the examples to reflect the changes above.

8) Updated the Bibliography. 

Once again, thanks for the careful read and all of the good suggestions.  

Thanks,

Bret


<TAXII_JSON_Message_Binding_Specification_v1.03.pdf>


Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg." 

On May 10, 2015, at 10:18 AM, Sergey Polzunov <[hidden email]> wrote:

Bret,

I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas

I noticed few things in this version of the spec:

-  Table 3.1-3 inconsistencies:
- “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
- SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.

- “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).

- How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..

- “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.

- Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas

Thanks,
Sergey Polzunov
Intelworks


On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:

Mark, et all,

I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.

<TAXII_JSON_Message_Binding_Specification_v1.02.pdf>


Thanks,

Bret



Bret Jordan CISSP
Director of Security Architecture and Standards | Office of the CTO
Blue Coat Systems
PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."

On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:

Bret,

I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.

Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
Section 1.3, message_id should be represented using the Courier New font

Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.

Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
- Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
- The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON

Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
- These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
- Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
- You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3

In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.

I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.

In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?

In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.

In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)

In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.

Table 3.5-1
- collection_information_response very nearly runs off the table
- This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
- I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”

Table 3.6-1 – The subscription_management_request is visually truncated by the table
Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document

Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column

Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?

Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?

As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.

Thank you.
-Mark


From: Jordan, Bret [[hidden email]]
Sent: Tuesday, April 14, 2015 10:49 PM
To: taxii-discussion-list Trusted Automated Exchange of Indicator In
Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01

I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  

While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.





TAXII_JSON_Message_Binding_Specification_v1.04.pdf (309K) Download Attachment
signature.asc (858 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.04

Sergey Polzunov
Nice! I’ll update the schemas.

> > 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>
> And now I remember why I did not do it in the first place, as it will mess up the data structure for the the Subscription Request message.

Ah, I see. Do you think renaming the fields only in Collection Subscription Response will be too confusing? I feel prefixes there are not necessary, because both “subscription_id” and “subscription_parameters” fields are under “subscription” parent field. In Collection Subscription Request they are at the highest layer, so having prefix there makes sense. This is not critical, of course.

> 4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different

Hm, I thought that field represented “Delivery Parameters”. Take a look at "4.4.7 TAXII Manage Collection Subscription Response” in TAXII 1.1 Spec. There are no other inbox services mentioned in that message definition.

Thanks,
Sergey Polzunov
Intelworks




> On 11 May 2015, at 22:41, Jordan, Bret <[hidden email]> wrote:
>
> I had to back one change out,
>
> > 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>
> And now I remember why I did not do it in the first place, as it will mess up the data structure for the the Subscription Request message.
>
> <TAXII_JSON_Message_Binding_Specification_v1.04.pdf>
>
> Thanks,
>
> Bret
>
>
>
> Bret Jordan CISSP
> Director of Security Architecture and Standards | Office of the CTO
> Blue Coat Systems
> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>
>> On May 11, 2015, at 2:19 PM, Bret Jordan <[hidden email]> wrote:
>>
>> Once again, thanks for finding those issues, here is an updated version with with your changes, v1.03.  I have also updated the APIs at https://github.com/jordan2175/freetaxii to reflect these changes so everything should work correctly.
>>
>>
>> Change Log
>>
>> 1) Table 3.1-3 has been updated so that SUPPORTED_BINDINGS is now called SUPPORTED_ENCODINGS to match the rest of the document.
>>
>> 2) In Table 3.1-3 SUPPORTED_CONTENTS was removed since it is not used in the JSON spec anywhere
>>
>> 3) In Table 3.6-1 “push_parameters" was renamed to “delivery_parameters" to better match the specification and give consistency with Table 3.8-1
>>
>> 4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different
>>
>> 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>>
>> 6) In Table 3.5-1 I renamed “polling_services” to be “poll_services” to match all of the user uses of just “poll” in the document.  
>>
>> 7) Updated the examples to reflect the changes above.
>>
>> 8) Updated the Bibliography.
>>
>> Once again, thanks for the careful read and all of the good suggestions.  
>>
>> Thanks,
>>
>> Bret
>>
>>
>> <TAXII_JSON_Message_Binding_Specification_v1.03.pdf>
>>
>>
>> Bret Jordan CISSP
>> Director of Security Architecture and Standards | Office of the CTO
>> Blue Coat Systems
>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>
>>> On May 10, 2015, at 10:18 AM, Sergey Polzunov <[hidden email]> wrote:
>>>
>>> Bret,
>>>
>>> I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas
>>>
>>> I noticed few things in this version of the spec:
>>>
>>> -  Table 3.1-3 inconsistencies:
>>> - “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
>>> - SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.
>>>
>>> - “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).
>>>
>>> - How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..
>>>
>>> - “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.
>>>
>>> - Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas
>>>
>>> Thanks,
>>> Sergey Polzunov
>>> Intelworks
>>>
>>>
>>>> On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:
>>>>
>>>> Mark, et all,
>>>>
>>>> I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.
>>>>
>>>> <TAXII_JSON_Message_Binding_Specification_v1.02.pdf>
>>>>
>>>>
>>>> Thanks,
>>>>
>>>> Bret
>>>>
>>>>
>>>>
>>>> Bret Jordan CISSP
>>>> Director of Security Architecture and Standards | Office of the CTO
>>>> Blue Coat Systems
>>>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>>>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>>>
>>>>> On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:
>>>>>
>>>>> Bret,
>>>>>
>>>>> I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.
>>>>>
>>>>> Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
>>>>> Section 1.3, message_id should be represented using the Courier New font
>>>>>
>>>>> Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.
>>>>>
>>>>> Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
>>>>> - Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
>>>>> - The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON
>>>>>
>>>>> Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
>>>>> - These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
>>>>> - Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
>>>>> - You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3
>>>>>
>>>>> In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.
>>>>>
>>>>> I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.
>>>>>
>>>>> In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?
>>>>>
>>>>> In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.
>>>>>
>>>>> In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)
>>>>>
>>>>> In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.
>>>>>
>>>>> Table 3.5-1
>>>>> - collection_information_response very nearly runs off the table
>>>>> - This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
>>>>> - I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”
>>>>>
>>>>> Table 3.6-1 – The subscription_management_request is visually truncated by the table
>>>>> Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document
>>>>>
>>>>> Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column
>>>>>
>>>>> Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?
>>>>>
>>>>> Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?
>>>>>
>>>>> As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.
>>>>>
>>>>> Thank you.
>>>>> -Mark
>>>>>
>>>>>
>>>>> From: Jordan, Bret [mailto:[hidden email]]
>>>>> Sent: Tuesday, April 14, 2015 10:49 PM
>>>>> To: taxii-discussion-list Trusted Automated Exchange of Indicator In
>>>>> Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01
>>>>>
>>>>> I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..  
>>>>>
>>>>> While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.
>>>>
>>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.04

Jordan, Bret


> On May 11, 2015, at 2:52 PM, Sergey Polzunov <[hidden email]> wrote:
>
> Nice! I’ll update the schemas.
>
>>> 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>>
>> And now I remember why I did not do it in the first place, as it will mess up the data structure for the the Subscription Request message.
>
> Ah, I see. Do you think renaming the fields only in Collection Subscription Response will be too confusing? I feel prefixes there are not necessary, because both “subscription_id” and “subscription_parameters” fields are under “subscription” parent field. In Collection Subscription Request they are at the highest layer, so having prefix there makes sense. This is not critical, of course.
>
It it more of a backend data structure thing for inheritance and structs..  I think we should revisit this and look at it when we do the next version based on the next version of TAXII.  I think some other subtle changes to the spec would make all of this a bit easier to use and understand anyway.

Nothing beats writing a companion spec and writing APIs to find weird issues… :)


>> 4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different
>
> Hm, I thought that field represented “Delivery Parameters”. Take a look at "4.4.7 TAXII Manage Collection Subscription Response” in TAXII 1.1 Spec. There are no other inbox services mentioned in that message definition.

There is a lot of other fringe areas I would like to address, but I feel right now it would deviate to much.  So yes, lets fix it, but lets do it in the next version that we do for the next version of TAXII.

Shortly after the OASIS TC gets setup I want to start talking about TAXII 1.2 and TAXII 2.0.  I am sure we will have a long laundry list of things to clean up and fix and now that we have more experience with TAXII, we will be better suited to have a more lively discussion.

Bret



>
> Thanks,
> Sergey Polzunov
> Intelworks
>
>
>
>
>> On 11 May 2015, at 22:41, Jordan, Bret <[hidden email]> wrote:
>>
>> I had to back one change out,
>>
>>> 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>>
>> And now I remember why I did not do it in the first place, as it will mess up the data structure for the the Subscription Request message.
>>
>> <TAXII_JSON_Message_Binding_Specification_v1.04.pdf>
>>
>> Thanks,
>>
>> Bret
>>
>>
>>
>> Bret Jordan CISSP
>> Director of Security Architecture and Standards | Office of the CTO
>> Blue Coat Systems
>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>
>>> On May 11, 2015, at 2:19 PM, Bret Jordan <[hidden email]> wrote:
>>>
>>> Once again, thanks for finding those issues, here is an updated version with with your changes, v1.03.  I have also updated the APIs at https://github.com/jordan2175/freetaxii to reflect these changes so everything should work correctly.
>>>
>>>
>>> Change Log
>>>
>>> 1) Table 3.1-3 has been updated so that SUPPORTED_BINDINGS is now called SUPPORTED_ENCODINGS to match the rest of the document.
>>>
>>> 2) In Table 3.1-3 SUPPORTED_CONTENTS was removed since it is not used in the JSON spec anywhere
>>>
>>> 3) In Table 3.6-1 “push_parameters" was renamed to “delivery_parameters" to better match the specification and give consistency with Table 3.8-1
>>>
>>> 4) I did NOT rename “inbox_services" to “delivery_parameters" in table 3.7-1 as I think it is a bit different
>>>
>>> 5) In Table 3.7-1 I renamed the two subscription fields as you suggested, super good catch.  Not sure how I missed those.
>>>
>>> 6) In Table 3.5-1 I renamed “polling_services” to be “poll_services” to match all of the user uses of just “poll” in the document.
>>>
>>> 7) Updated the examples to reflect the changes above.
>>>
>>> 8) Updated the Bibliography.
>>>
>>> Once again, thanks for the careful read and all of the good suggestions.
>>>
>>> Thanks,
>>>
>>> Bret
>>>
>>>
>>> <TAXII_JSON_Message_Binding_Specification_v1.03.pdf>
>>>
>>>
>>> Bret Jordan CISSP
>>> Director of Security Architecture and Standards | Office of the CTO
>>> Blue Coat Systems
>>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>>
>>>> On May 10, 2015, at 10:18 AM, Sergey Polzunov <[hidden email]> wrote:
>>>>
>>>> Bret,
>>>>
>>>> I’ve aligned the schemas with the latest version of the bindings. The repo was moved - https://github.com/Intelworks/TAXII-JSON-schemas
>>>>
>>>> I noticed few things in this version of the spec:
>>>>
>>>> -  Table 3.1-3 inconsistencies:
>>>> - “message_bindings” field was renamed to “encodings” but the constant is still SUPPORTED_BINDINGS. Should it be SUPPORTED_ENCODINGS?
>>>> - SUPPORTED_CONTENTS constant defined though “Content Bindings” are not used anywhere in the spec.
>>>>
>>>> - “Delivery parameters” are called “push_parameters” in Managed Collection Subscription Request (Table 3.6-1), “inbox_services” in Managed Collection Subscription Response (Table 3.7-1) and “delivery_parameters” in Poll Request (Table 3.8-1). One name should be used for the concept. I propose to name it “delivery_parameters”. This name will match the name used in TAXII 1.1 Spec and is generic enough to accommodate changes in the future (maybe Inbox Service will not be the only delivery option).
>>>>
>>>> - How about changing “subscription_id” into “id” and “subscription_parameters” into “parameters” in Managed Collection Subscription Response (Table 3.7-1)? That would nicely align with other name changes..
>>>>
>>>> - “poll_services” field in Managed Collection Subscription Response (Table 3.7-1) while everywhere else it is “polling_services”.
>>>>
>>>> - Github URL (in Bibliography, 3) has changed to https://github.com/Intelworks/TAXII-JSON-schemas
>>>>
>>>> Thanks,
>>>> Sergey Polzunov
>>>> Intelworks
>>>>
>>>>
>>>>> On 28 Apr 2015, at 00:44, Jordan, Bret <[hidden email]> wrote:
>>>>>
>>>>> Mark, et all,
>>>>>
>>>>> I have implemented all of the suggestions and changes outlined below.  Please accept this new version, v1.02, for formal nclusion on the TAXII website.
>>>>>
>>>>> <TAXII_JSON_Message_Binding_Specification_v1.02.pdf>
>>>>>
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Bret
>>>>>
>>>>>
>>>>>
>>>>> Bret Jordan CISSP
>>>>> Director of Security Architecture and Standards | Office of the CTO
>>>>> Blue Coat Systems
>>>>> PGP Fingerprint: 62A6 5999 0F7D 0D61 4C66 D59C 2DB5 111D 63BC A303
>>>>> "Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
>>>>>
>>>>>> On Apr 15, 2015, at 8:05 AM, Davidson II, Mark S <[hidden email]> wrote:
>>>>>>
>>>>>> Bret,
>>>>>>
>>>>>> I finally went through this with a fine-toothed comb and have feedback. There’s a lot of it, but it’s mostly nit-picky stuff that hopefully isn’t controversial. My apologies for the delay in getting through this.
>>>>>>
>>>>>> Section 1.2, sentence that reads “JSON element names…” – the example JSON name is not represented in Courier New Font.
>>>>>> Section 1.3, message_id should be represented using the Courier New font
>>>>>>
>>>>>> Section 2.2.2 introduces the use of “options” for Extended Headers. I will take the position that this should not be done, as it creates a nuance/pitfall (remembering that they are Extended Headers everywhere in TAXII except in this specification) that doesn’t provide any benefit, other than the author liking the word “options” better.
>>>>>>
>>>>>> Section 2.2.2, the sentence that reads: “The value of an Extended Header MUST be a string and value of a Status Detail MUST be either a string or arrays of strings.”
>>>>>> - Why can’t extended headers be an array of strings, but Status Details can be an array of strings? These should either be aligned or the discrepancy should be explained in the document.
>>>>>> - The sentence should end with “… either a string or an array of strings”. Since this is a normative sentence (it contains MUST), particular attention should be paid to wording. From a practical standpoint, I’m not sure arrays of strings - {‘foo’: [‘1’], [‘2’]}  – is (are?) valid JSON
>>>>>>
>>>>>> Section 1.3 notes that all JSON structures are a name/value pair, object, or array. Section 3, ‘type’, lists a different set of types (string, boolean, object, array, array of objects).
>>>>>> - These sections should be updated for consistency. I’m not sure if they necessarily disagree, but the alignment should be more clear than it is now.
>>>>>> - Is array of objects sufficiently distinct from array to be called out? My guess is that it’s not
>>>>>> - You may want to comb through the doc, identify the list of all types used, and use that list for the basis of both section 1.3 and section 3
>>>>>>
>>>>>> In your message tables, there’s some odd formatting. (e.g., the ‘id’ field of section 3.1). I’d recommend merging the cells of the table. If you’re using MS Word, select the tables, right click, and select “merge cells”. I’d also recommend merging the vertical cells like we do in the TAXII specifications.
>>>>>>
>>>>>> I’ll also note that these tables do not use the Courier New Font as described earlier in the document. Since this is a stylistic choice, I’ll leave it to your decision on whether to remove the statement about Courier New, or to update the tables to use Courier New.
>>>>>>
>>>>>> In Table 3.1-1, for options and details: Options is not well specified, and details is slightly better. However, I think the phrasing “The value field…” implies that there is only one value field, which is not the case. Perhaps something like “Value fields in this object are constrained to being either a string or an array of strings” ?
>>>>>>
>>>>>> In table 3.1-3, I’d recommend using “Indicates” instead of “Indicating”. If I was smarter at grammar, I’d say “don’t use the present perfect progressive tense”, but I had to search for “ing tense” just to get that far, so I won’t pretend to be smarter than I am.
>>>>>>
>>>>>> In table 3.1-3, I’d recommend indicating (how’s that for irony?) which values are allowed in the arrays. E.g., for SUPPORTED_BINDINGS, “An array of strings indicating …” (Yes, the -ing tense works for me here. Yes, I’m now questioning my sanity)
>>>>>>
>>>>>> In table 3.1-3, why is options at the bottom? It’s consistently at the bottom, which is good. And, since this is JSON and not XML, the order doesn’t really matter. But, it is considered a “header” and (IMO) is a good candidate to go at the top of the message.
>>>>>>
>>>>>> Table 3.5-1
>>>>>> - collection_information_response very nearly runs off the table
>>>>>> - This probably goes for everything. I’m looking at the ‘collections’ field, and it seems that a note could be “The value for collection is an array of objects, and each object has only the fields defined in this document” or something to that effect.
>>>>>> - I notice a similar thing for encodings – it might be useful to say something like “an array of strings indicating …”
>>>>>>
>>>>>> Table 3.6-1 – The subscription_management_request is visually truncated by the table
>>>>>> Table 3.6-1 – RE: The query field. This would lead me to potentially construct something like query: {‘key’: ‘somekey’, ‘value’: ‘somevalue’}, which I think is not intended. Perhaps in the notes field, describe that key is not the literal key? I think this goes for all query fields in the document
>>>>>>
>>>>>> Table 3.7-1 – The “in_response_to” notes use the “message_id” term, whereas only “id” is used in the field name column
>>>>>>
>>>>>> Table 3.9-1 – I notice the use of default values. In XML, you can set the parser to “supply the defaults” when parsing the document. Is there a similar notion for JSON? Perhaps say something like “Absence of this field indicates …” so that it’s explicitly stated?
>>>>>>
>>>>>> Table 3.10 – destination_collection_names – the notes section implies that there can be more than one instance of the field, which isn’t true in JSON. Should this be implemented as an array of strings?
>>>>>>
>>>>>> As a positive note, the eamples are very useful. Maybe there should be one demonstrating extended headers as well? This could be incorporated into an existing example.
>>>>>>
>>>>>> Thank you.
>>>>>> -Mark
>>>>>>
>>>>>>
>>>>>> From: Jordan, Bret [mailto:[hidden email]]
>>>>>> Sent: Tuesday, April 14, 2015 10:49 PM
>>>>>> To: taxii-discussion-list Trusted Automated Exchange of Indicator In
>>>>>> Subject: [TAXII] Formal Submission of JSON Message Binding for TAXII 1.1, v1.01
>>>>>>
>>>>>> I finished updating my APIs to support the changes and they are all pushed to GitHub…  However, no matter how many times you proof read…..
>>>>>>
>>>>>> While updating the APIs I discovered a type’o in the field names in section 3.6 and 3.10.
>>>>>
>>>>
>>>
>>
>


signature.asc (858 bytes) Download Attachment