Confusing "Type" in GitHub's form schema

[Lemmingh]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema

What part(s) of the article would you like to see updated?

https://github.com/github/docs/blob/954e58c470ffce11cd94b1c1fc2efedb41e73690/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema.md#L66-L67

Problem

I guess for most people, "hash" is the return value of a hash function.

But here, it seems to mean "dictionary", aka "associative array".

Suggestion

Please consider an appropriate term, like "dictionary".

---

Additional information

[maintainers edit]

Content plan

For consistency with our GitHub Actions documentation, let's go ahead and change the type to map for both the attributes and validations keys.

[welcome[bot]]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@Lemmingh Thanks so much for opening an issue! I'll triage this for the team to take a look :eyes:

[vgrl]

Thanks for opening this issue and for your patience as we review! I've spoken with the team and they believe that using the hash type communicates the concept better than some other terms, and have therefore asked that we don't change the type used in this article.

We can however add clarification by expanding the key Description to start with “A node containing a set of key-value pairs…”, where node is a common YAML native data structure.

| attributes | A node containing a set of key-value pairs that define the properties of the element. | Required | Hash | {% octicon "dash" aria-label="The dash icon" %} | {% octicon "dash" aria-label="The dash icon" %} | | validations | A node containing a set of key-value pairs that set constraints on the element. | Optional | Hash | {% octicon "dash" aria-label="The dash icon" %} | {% octicon "dash" aria-label="The dash icon" %} |

You or anyone else is welcome to open a PR with the above fix 🔨 for this issue!

[Lemmingh]

they believe that using the hash type communicates the concept better

I'm afraid I don't understand.

Describing an "associative array" as "hash" is definitely wrong.

It violates established terms in computer science

A sane data structure textbook would define the term "hash" as:

• (NOUN) A value produced by a hash function.

• (VERB) To calculate a hash value.

A textbook would say:

attributes:
  label: 'Proposal'
  description: 'A clear and concise description of your idea.'

The attributes contains an "associative array" (aka "dictionary", "map", etc.), which is a key-value pair collection where each key may appear at most once. An "associative array" is usually implemented as some kind of "hash table" or "binary search tree".

Given that "associative array" is cryptic for those without computer science background, many textbooks choose "dictionary" as the primary term, that is:

"dictionary" (aka "map", "associative array", etc.)

A schema should express abstract data types, not implementation details

The "hash" type probably comes from something in your back-end code.

But a schema is expected be a purely logical description.

Abstract data types are logical shapes and operations, independent of implementation.

The YAML spec revision 1.2.2 uses "mapping":

The content of a mapping node is an unordered set of key/value node pairs, with the restriction that each of the keys is unique.

Note that "map" is also an alias of "associative array", an abstract concept.

[Lemmingh]

In short, you cannot say a wrong term is better than a correct term.

[jsoref]

The actions documentation uses Map: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions

[vgrl]

Thanks @Lemmingh and @jsoref for your input and explanation ❤️ , I'll convey this info to the team, and update you as soon as I have more to share.

[Anika-Roy]

Hi! Im participating in Hacktoberfest and I'd like to know if this issue is counted in Hacktoberfest and if I can work on it?

[jsoref]

I wouldn't. This appears to be waiting on the internal team.

[cmwilson21]

👋 @Anika-Roy Thanks for your willingness to work on this. As @jsoref mentioned, this one is waiting for a bit more information from our internal team. For now, I'm going to remove the help wanted label so it doesn't show up on our board until we've confirmed it with our team.

We are participating in Hacktoberfest! 🎃 Feel free to head over to the help wanted board and pick up any of our open issues. 💛

[vgrl]

Thanks for your patience @Lemmingh :pray::skin-tone-2: :bow::skin-tone-2: while we discussed this issue internally. For consistency with our GitHub Actions documentation, let's go ahead and change the type to map for both the attributes and validations keys.

You or anyone else is welcome to open a PR with the above fix 🔨 for this issue!