仕様の表現の明確化: a. 属性値 列における表現内容と b. デフォルト 列における (必須) "" などの表現及び undefined の明記化について

[usagi]

問題の位置

• https://github.com/gsi-cyberjapan/layers-dot-txt-spec/blob/master/specifications.md#%E8%A6%8F%E5%AE%9A

↑規定の Layer, LayerGroup 項の a. 属性値 列 と b. デフォルト 列。

問題の内容

a. 属性値 列

1. 用語として「属性値」を用いているのに実際には「型」が記述されています。
   • Layer はかろうじて属性値といえなくもありませんが、その場合も一般的には "Layer" のように文字列値である事がリテラルから自明な表現にします。そのようにしない場合は一般的に仕様書の読者は対象を型としての Layer と読んでしまう可能性がとても高く、仕様書から期待されない意図を読んでしまいます。
   • 推量として Property-value を和訳した語を充てたのだろうと思いますが、コンテキスト上その意味での「属性値」は具体的な値の事を指し、ここで現在表現されている 文字列 や L.TileLayerと同じ はおそらく「型」です。 L.TileLayerと同じ のリンク先でも table では Type = 型 の部分への対応を想定しているような気配ですから、「属性値」では仕様の表現に不具合があります。
2. この列の記述には「型」と「許容される値」が混在してしまっています。一般的に仕様書としては仕様が明確に伝わらないためよくありません。具体的な例としては:
   • Layer は「許容される値」で 文字列リテラルとわかるよう "Layer" とした上で「属性値」ではある
   • 文字列 は「型」なので「属性値」ではありません。
   • URL は「型」としては String かつ、「許容される値」としては "Layer" のような variant の1つではなく URL を満たす文字列値という制約条件(whereされるconditionとか言語によっては Trait や Interface だったりするようなもの)です。
   • true/false は「許容される値」です。これは Boolean 型のすべての variant なので、つまり「型」を間接的に規定しているような具合です。
   • L.TileLayerと同じ は参照先の table では Type しかないので、参照元が「属性値」では不整合で仕様を読む開発者に混乱を招きます。この点からも「型」列への置き換えが良好な選択肢として示唆されます。
3. この列は事実上「型」を定義していますから、「文字列」のような部分的な和訳表現、型の名前の和訳表現ではなく、型のシンボル、キーワードそのものを記述するのが開発者向けの仕様としては望ましいです。「文字列」ではなく String です。もし、「属性値」の制約条件として間接的に記述したい場合は「文字列」ではなく「任意の値」が妥当かもしれません。

b. デフォルト 列

1. コンテキスト上は一般的に、デフォルト = default は未定義 ≈ undefined のプロパティーが参照される事があった場合またはそれに準じる null などの無効値に変えて返される有効な何らかの規程 "値" の事を言います。
   • 例: あるオブジェクトの .hoge プロパティーには Number が設定されている事が期待されるが、 undefined または null または Number 以外の値が入っていた場合は -1 をデフォルト値として読み出す
2. (必須) は"デフォルト値"を表す表現ではないので、その行のプロパティーが undefined を許容するか、しか定義できていません。おそらく、 undefined を許容しない ≈ 省略不可の意図を仕様化したかったであろう事は推量できます。但し、繰り返しとなりますがそれは"デフォルト"で表現される事ではありません。
3. true, "" などは列のヘッダー "デフォルト" から文字通り、おそらく意図通りのデフォルトとして扱うべき値である事を読み取れます。それら自体には問題ありません。しかし、この仕様の記述、デフォルト列の記述方法では、前述(2)のように「デフォルト」と「省略可否」が混用されているため、結果として true, "" などデフォルト値が正しく記述された各行では省略可能なのかが仕様書の読者には不明瞭です。

期待される解決方法

以下のすべてを行います:

a. 属性値 列

1. ヘッダーの「属性値」を「型」へ表現変更します。
2. Layer はその行の型 String にし、「意味」列に Layer である事を示す。値は "Layer" に固定され他の値は許容されない。 のように制約条件の記述を移動する。
   • 値に明確な制約条件の表示が必要な場合は現在は Layer のみなので、わざわざ制約条件の列を table へ追加する必要はないかな、と思います。
   • LayerGroup も同様
3. 文字列 は String に変更
4. URL は String に変更。「意味」列で URL の制約条件を満たさない場合は無効である事が自明なため特に制約条件としてURLを満たす文字列云々の明示は事実上不必要と思います。
5. true/false は Boolean に変更
6. Layer 及び LayerGroupの配列 は [ Layer | LayerGroup ] と記述すれば仕様を必要とする開発者にはフレンドリーです。 [ Layer or LayerGroup ] または [ Layer または LayerGroup ] のように記述しても配列要素の型に相当する variant は仕様を必要とする開発者におそらく明確に伝わります。
   • Note: 一般に、または法律用語などでも「及び」は AND を意図することばとして用いられるため、この表現では「または」 OR として表現のうちの何れかの意図が明瞭にするのがよいと思います。

b. デフォルト 列

1. 「省略可否」列を追加し、その行のプロパティーが undefined (≈省略) を仕様として許可するか読者が明確に判断できる表現を行います。列名はECMAScript開発者向けに正確さを優先したい場合は「undefined の許容」のような表現としてもよりわかりやすいかもしれません。
   • この列に記述する内容は 可/否 または 可/不可 のような表現にします。
   • 現在「デフォルト」列で (必須) が設定されている行はおそらく、この列に 不可 と記述して表現を移動する事になります。
   • 現在「デフォルト」列で （entries属性かsrc属性のいずれかが必須） が設定されている行は 可 ( 但し entries または src の何れかは有効な事) のような記述になります。
2. 「デフォルト」列の内容の変更
   • 現在 (必須) が設定されている行は n/a となりますので空欄または n/a 表記とします。
   • undefined または規定された内部表現の型として有効ではない場合 (≈ null, Number が期待される行で "hoge" 文字列値が入っていたなど)
3. 「デフォルト」を読み出す条件を明確に定義し、仕様に追加します。
   • undefined -> default として扱うか
   • null -> default として扱うか
   • 期待しない内部表現型 -> default として扱うか
   • 期待しない内部表現型だが型の変換が有効な場合 -> 型の変換を許容し有効な値とするか、型の変換を許容せず default として扱うか

c. その他の些細な修正

1. 「属性名」、「型」、「デフォルト」はコードとして有効なキーワードや値に準じるものなので、 markdown のソースとしてはバッククォートで囲み意図を明確に伝えやすい表現が行われるように修正します。 (JSON=ECMA-404では厳密には String 表現なので "type" のようにはなりますが、これは便宜上 type としても開発者が意図を読み違える事はまずありません)

[johofukyu]

ご指摘ありがとうございます。
改めてプログラムを確認の上、表の修正を検討いたします。