Editorial issues from Yekaterina

[ghost]

Capture editorial issues from Yekaterina. If anything turns out to be substantive, I'll open a separate issue.

[ghost]

Yekaterina:

Thanks for such a thorough reading. I addressed the bulk of your issues in a single change draft, and opened issues to track your substantive feedback:

• Issue Associate descriptor metadata with thread flow locations #381: Associate descriptor metadata with thread flow locations
• Issue Make certain invocation and versionControlDetails properties redactable #390: Make certain invocation properties redactable

Thanks,
Larry

---

p. 2: Should we update the copyright date on the title page and in the footer?

Status: Done. Also updated version number and added Chris Meyer to Acknowledgments.

---

§1.2, p. 15: described in [BCP14] [RFC2119] [RFC8174] => "described in these specifications"

Response: Provide the specifications titles and treat the cross-references as parentheticals, as @kupsch suggested as part of #366.

---

§2.2, p. 24: "by" => "by JSON"

Response: Done.

---

§2.4, p. 24: "(EBNF) defined in" => "(EBNF)"

Response: Done.

---

§2.4, p. 24: "according to" => "according to the standard"

Response: => "according to JSON"

---

§3.1, p. 26: "described in" => "described in the standard"

Response: => "specified by JSON"

---

§3.1, p. 26: "[RFC8529] requires" => "The standard [RFC8529] requires"

Response: => "JSON [RFC8529] requires"

---

§3.3.2, p. 26: "that" => "that the standard"

Response: => "that JSON" (previously addressed as part of #366)

---

§3.4.1, p. 27: "in" => "in the URI standard"

Response: Done

---

§3.5.4, p. 31: "RFC4122" -> "The standard [RFC4122]"

Response: => "The UUID standard [RFC4122]"

---

§3.7.3, p. 33: "described in JSON Schema" => "described in the JSON Schema"

Response: => "described in the JSON Schema standard"

---

§3.9, p. 34: "compatible with" => "compatible with the ISO standard"

Response: => "the ISO standard for date and time formats"

---

§3.10.1, p. 35: "in" => "in the standard" (first occurrence on this page)

Response: => "in the URI standard"

---

§3.10.1, p. 35: "by" => "by the standard"

Response: Done.

NOTE: I decided to specify the standard "name" ("in the URI standard") the first time a reference occurs in a numbered section, and to just say "in the standard" for subsequent references to the same standard in the same section. This is similar to my practice for section cross-references.

---

§3.10.1, p. 35: "in" => "in the standard" (second occurrence on the page)

Response: Done.

---

§3.10.1, p. 36: "see" => "see the standard"

Response: Done.

---

§3.10.2, p. 36: "see" => "see the standard"

Response: Done.

---

§3.10.2, p. 37: "to" => "to the standard"

Response: => "to the URI standard"

---

§3.10.4, p. 37: "specified in [RFC3987] §3.1" => "specified in the standard [RFC3987] §3.1"

Response: => "specified in §3.1 of the standard [RFC3987]"

---

§3.10.4, p. 37: "[RFC3987] §3.1" => "The standard [RFC3987] §3.1"

Response: => "§3.1 of the standard [RFC3987]"

---

§3.10.4, p. 37: "[RFC3987] §3.1" => "the standard [RFC3987] §3.1"

Response: => "§3.1 of the standard [RFC3987]"

---

§3.14.2, p. 47: Lower-case property names in second column of table.

Response: Yes, previously addressed. (This is now in §3.15.3.)

---

§3.14.7, p. 50: "by" => "by the standard"

Response: => "by the language tags standard"

---

§3.14.23, p. 56: "in" => "in the standard"

Response: "one of the character set names specified in [IANA-ENC]" => "one of the character set names defined by IANA [IANA-ENC]"

---

§3.18.8, p. 67: "by" => "by SemVer"

Response: => "by Semantic Versioning" (previously addressed as part of #366)

---

§3.18.19, p. 69: "by" => "by the standard"

Response: => "by the language tags standard"

---

§3.19.15 – §3.19.20: Should these properties be redactable?

Response: That's a really good and subtle question. Yes. I opened Issue #390, "Make certain invocation properties redactable."

---

§3.22.3 – §3.22.6: Should these properties be redactable?

Response: Still pondering this one. I'll track it as part of #390.

---

§3.23.9, p. 89: "in" => "in the standard"

Response: "one of the character set names specified in [IANA-ENC]" => "one of the character set names defined by IANA [IANA-ENC]"

---

§3.24.1, p. 92: Mixed font sizes in example

Response: Good heavens, how did you even see that? :-) No, it's not intentional. Fixed here. Even I don't have the heart to scrub for this, but if you see other examples, let me know.

---

§3.24.6, p. 92: Typo: "dowloadUri" => "downloadUri"

Response: Fixed

---

§3.24.7, p. 92: Typo: "dowloadUri" => "downloadUri"

Response: Fixed

---

§3.25.3, p. 93: Why shouldn't a direct producer set result.guid?

Response: Because that property is meant for the use of the result management system (see the next sentence).

Now in some cases the distinction between the tool and the RMS might be fuzzy; the tool might be optimized to work with a particular RMS. If so, you can consider the tool to be part of the RMS and set the guid property.

---

§3.25.5, p. 94: "CA201" => "CA2101"

Response: Fixed.

---

§3.25.12, p. 102: With regard to EXAMPLE 4: "In case of Fortify, we would report these as separate results, and there is no existing mechanism for determining that these results are all about the same variable."

Response: The example is wrong to say that the tool "must" produce a single result in this case. It's wrong for two reasons. The technical one is that examples can't include normative language like "must". The important one is that the statement in the example is wrong. The actual normative text, above, says that you can specify multiple locations only if all the occurrences have to be corrected together. It does not say that you have to specify multiple locations in that case; it is permissible to report each location in a separate result.

So I changed the example to say that the tool "might" produce a single result.

---

§3.25.17, p. 103: I am still confused which situation requires the use of fingerprints, and which – the use of partialFingerprints. Is the idea that fingerprints are generated based on partialFingerprints, in which case Fortify should be using partialFingerprints to store their guids?

Response: I will respond in email and loop @michaelcfanning in, since he's sometimes more successful at explaining this than I am. But I'll take the first crack at it.

---

§3.25.18, p. 105: "more than code flow" => "more than one code flow"

Response: Fixed (previously addressed).

---

§3.25.21, p. 106: "collects" => "collect"

Response: Fixed (previously addressed).

---

§3.25.23, p. 107: "an null" => "a null"

Response: Removed "an" (previously addressed).

---

§3.28.2, p. 114: Confusing sentence

Response: I think it's the word "partially" that's the problem. I removed it and it reads fine to me now.

---

§3.28.4, p. 116: "show" => "shown"

Response: Fixed (previously addressed).

---

§3.28.12, p. 117: "it SHALL" – extra space

Response: Fixed.

---

§3.29.2, p. 118: "by" => "by the standard"

Response: => "by the JSON Schema standard"

---

§3.30.7, p. 120: "addreses" => "addresses"

Response: Fixed (previously addressed).

---

§3.31.8, p. 124: Do XML Path indices start at 1 or 0? (two occurrences)

Response: They start at 1. The spec is correct. See XML Path 2.5, Abbreviated Syntax, the 6th bullet point:

• para[1] selects the first para child of the context node

---

§3.32.2.4, p. 127: Sentence ends in a comma.

Response: Fixed (in the course of completely reworking this section, previously addressed).

---

§3.32.3, p. 128: "and and"

Response: Fixed (previously addressed).

---

§3.31.1, p. 129: "one more" => "one or more"

Response: Fixed (previously addressed).

---

§3.42, p. 139: Is there currently a way to associate a threadFlowLocation with a rule? I know that a result is associated with a rule, but in Fortify, some parts of our dataflow paths are triggered by a rule, and therefore there are several rules each of which is associated with a particular location in the flow that contribute to the result.

Response: Per discussion in TC #35, we will provide support for these "helper rules." This is tracked in a separate issue, #381, "Associate descriptor metadata with thread flow locations."

---

§3.43.5, p. 145: "of" => "of the standard"

Response: => "of the HTTP standard"

---

§3.44.5, p. 147: Confusing sentence

Response: Fixed (previously addressed). The problem was the word "in" ("the status code in that describes"). Removed it: "the status code that describes".

---

§3.46.3, p. 150: "contain a containing" => "contain"

Response: Fixed (previously addressed).

---

§3.52.3, p. 164: "effect" => "affect"

Response: The spec is correct. "Effect" is usually used as a noun, but it is also a verb meaning to cause or to bring about:

effect vt (1533) 1 : to cause to come into being 2 a : to bring about often by surmounting obstacles ... b to put into operation...

(Merriam Webster's Collegiate Dictionary, Tenth Edition, p. 367)

In this case "to effect the fix" == "to achieve the fix".

---

§4.3.3, p. 173: "be default" => "default"

Response: Fixed (previously addressed).

---

§4.3.5, p. 173: "belongs contained" => "contained"

Response: Fixed (previously addressed).

---

Appendix A, p. 177: Is Smith Douglas the same person as Douglas Smith?

Response: Yes, fixed (previously addressed). Good catch!

---

Appendix B, p. 178: "does need" => "does not need"

Response: Fixed. I could've sworn I previously addressed this one, but apparently not.

---

Appendix C, p. 179: "tool provide" => "tool provides"

Response: The spec is correct. This is the subjunctive mood:

For instance: ... "It is required that he go to the back of the line" (compared with the present indicative "Everyone knows that he goes to the back of the line").