The introductory section on entities is confusing

[steko]

First of all thanks for your effort with the Linked CSV proposal, it is really promising IMHO. A clear format could be even adopted by spreadsheet software!

In the introductory section to entities ("2.1 Identifiers") there is too much confusion among symbols: $, @' and#' are mentioned and shown in different cases but it is not clear from an outside perspective:

• why the JSON in example 4 has @id instead of `id'
• that the values in the id column start with a # so the resulting URI can be in the form http://example.org/countries#AF (is it really so?)

A clearer distinction could be made between the prefix of column names (e.g. id) and the prefix of fields. Having '#' also used for the prolog column adds to the confusion I am afraid.

[JeniT]

That's really helpful feedback, thank you!

The JSON uses @id rather than id because it follows JSON-LD. We could make that more explicit or drop that requirement.

The values in the $id column are interpreted as URIs, so if you start them with # then they're interpreted as fragment identifiers on the URIs, and resolve based on the base URI of the linked CSV file. That's why #AF in that column resolves to http://example.org/countries#AF.

I understand that all this line noise and the different characters is confusing. Would it be better to use $meta and $id for the columns that have special significance in Linked CSV?

[steko]

I think that adding the more detailed explanations you provide here is a good way to make it more easily understood. So for example:

The prefix $ is used because the prefix @ is interpreted as indicating a formula when entered into spreadsheet programs such as Excel.

but there is no indication of why @ would be preferable (JSON-LD, as seen in the example below, perhaps there could be a link to it?).

Ditto for the values in $id columns and concatenating them to create a URI.

$meta looks definitely better than `#' (“explicit is better than implicit” I may say).