[QUESTION] Explain about deprecation .yml on entities on docs

[shakaran]

As far I could read in "latest" doc (which is related to Doctrine 2.x) it seems that still .yml entities are supported
http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/yaml-mapping.html

But from some github issues that I read (not sure if it is written in other place), it seems that from 2.6 or 2.7 an future 3.x from Doctrine, the entities with .yml format will be deprecated and not supported anymore.

I would like know some technical explanation (or maybe not technical) of why drop the support for YML in favour of annotations or XML only. I just try to understand why, I don't judge if keep it is better o not.

Specially for non very technical people, understand a yml file is more easy than anotations or XML and sometimes is more quick to write in yaml format (manually) than XML or annotations

[Ocramius]

@shakaran few things here:

1. this is a dev tool, intended to be used by developers. Non-devs have no business in defining mappings
2. YAML lacks a proper DTD/XSD/Schema system and/or integration with editors that enforces structure in it
3. anyone can type following in any modern IDE of choice and get auto-completion without having to even read the docs about mappings (some of it is even optional):

   <?xml version="1.0" encoding="UTF-8"?>
   <doctrine-mapping
       xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="./vendor/doctrine/orm/doctrine-mapping.xsd"
   >
       <!-- now simply CTRL+SPACE through the day :-) -->
   </doctrine-mapping>

4. you get visual alerting (by your editor) that something is wrong with your mappings even before you run anything within the context of the ORM
5. there is no proper way to help users that paste in their mappings, since visual validation requires deep knowledge of the existing keys rather than just pasting the mappings in an editor and just checking whether something is wrong. From the perspective of somebody providing support, helping somebody that writes YAML mappings in a Github issue is a nightmare, as everything needs to be checked manually against the YamlDriver.
6. XML parsers are old and extremely stable beasts that are also extremely efficient
7. YAML is hard to read (typical example with "country: no") and hard to write (indentation errors): it is by far a good tool for something as important as configuration

From our point of view (doctrine project), YAML mappings are overhead and added work for little to no benefit to the community besides personal taste of some users.

Strict configuration formats like Doctrine ORM mappings MUST be provided within a strict validation framework, in this case provided by static analysis of annotations or XSD/DTD validation in XML.

[Ocramius]

Related: symfony/symfony-docs#6752
Related: doctrine/orm#5932

[shakaran]

@Ocramius thanks for you time and explanations, very clear to me now ;)

[alirezakazemi]

@shakaran few things here:

1. this is a dev tool, intended to be used by developers. Non-devs have no business in defining mappings

2. YAML lacks a proper DTD/XSD/Schema system and/or integration with editors that enforces structure in it

3. anyone can type following in any modern IDE of choice and get auto-completion without having to even read the docs about mappings (some of it is even optional):
   ```
   <?xml version="1.0" encoding="UTF-8"?>
   <doctrine-mapping
       xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="./vendor/doctrine/orm/doctrine-mapping.xsd"
   >
       <!-- now simply CTRL+SPACE through the day :-) -->
   </doctrine-mapping>
   ```

4. you get visual alerting (by your editor) that something is wrong with your mappings even before you run anything within the context of the ORM

5. there is no proper way to help users that paste in their mappings, since visual validation requires deep knowledge of the existing keys rather than just pasting the mappings in an editor and just checking whether something is wrong. From the perspective of somebody providing support, helping somebody that writes YAML mappings in a Github issue is a nightmare, as everything needs to be checked manually against the [`YamlDriver`](https://github.com/doctrine/doctrine2/blob/v2.6.0/lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php).

6. XML parsers are old and extremely stable beasts that are also extremely efficient

From our point of view (doctrine project), YAML mappings are overhead and added work for little to no benefit to the community besides personal taste of some users.

Strict configuration formats like Doctrine ORM mappings MUST be provided within a strict validation framework, in this case provided by static analysis of annotations or XSD/DTD validation in XML.

Its true that XML benefits XST/DTD/Schema. But nothing is perfect including XML. Eventhough XML is a text representation, it is more machine readable rather than human readable, It is too verbose. But YAML although currently lackes DTD/Schema facilities, but is just kind of the pure data. It Elegantly imposes structure on data without the need for messing symbols. A single look on yaml presents data to the developer at a second but It takes more than 10 seconds to read the same XML.

Human compatibility is not an irrelevant feature at all. It is the reason for the success of text based network application protocols like HTTP, SMTP, etc. So I think is too important.

So It was not so wise to remove support for the yaml presentation. If the tooling dev support was the reason someone could provide converters to XML or Annotations and the remaining processing would work on a single (e.g. XML) presentation.

Morover YAML theoretically could have something like DTD/Scheam although currently it may lack one.
As an example I refer you to the Symfony 1.x Schema notation and tooling which defined a schema for some data. Some tools the then generated PHP parsing codes from schema which could then parse the YAML fixtures (as data).
I know that the schema which was written in schema.yml was itself schema less. But this is just an approximate example to show that YAML may be improved to have a true schema some day. However I think even before having a strict DTD/Schema it is superior in some aspects. XML & YAML both are data presentation languages which can have exactly the same features but other than YAML currently lacks a developed or well-known schema and XML suffers from verbosity and readability.

As you mentioned about being used by Developers not ordinary users, I should mention even 16 year developers (like me) is also a human not a machine and it is better to make things ergonomic.

About availability of using IDE/Intellisense, ... its true, but just in the context of creating new code/data and not in the context of reading previous code/data. Even during developing new code one requires frequently reading previous code.

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

[bertoost]

OH NO! Yaml should not be removed!! please

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

So true!

[Majkl578]

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

Few points:

• YAML is definitely not the most simple, quite the opposite, with all the madness around labels, references, assisted copy-paste etc.
• It's human readable as long as simple it contains simple data. When it contains more complex data, like multi-lines or abovementioned referenctes, it's no longer simple and readable.
• It seems to be powerful, but with great power comes great responsibility. And YAML is sacrificing straightforwardness and simplicity for power.
• YAML is not a data presentation language in our context, it's definition language as it is used for configuration.
• It's prone to multiple ambiguities, offset-by-one indentation errors or arrays as few examples.

[legalcash]

Do not remove YAML is not it easier than to remove it?

Then there will be both options as it was - "and the sheep are safe and the wolves are full"

[stof]

@legalcash the difference is not "remove or not remove". It is "remove the yaml driver or maintain it". Keeping the YAML driver is not a no-op choice. And the ORM maintainers decided to drop it from 3.0.
Note that DoctrineBundle can change anything to this (if there is no yaml driver in the ORM, we simply cannot configure some mapping using it in the bundle)

[onavascuez]

And, what do you think about replace YML to JSON?
Avoid space and indention problems, is too much easy to process, etc. No?

[alcaeus]

Same difference: it still requires us to create a dedicated mapping driver for JSON. I previously thought about using symfony/config for the purpose of extracting mapping data from XML or YAML (or whatever else symfony/config allows you to use) into arrays, and then use that for mapping.

There are a few reasons why I haven't started working on that:

1. Metadata is getting rewritten for Doctrine ORM 3. While I don't know how long that's going to take, I understand it will do away with different mapping drivers and be based on arrays
2. We currently use an XSD to validate the XML mappings and to provide code completion in your IDE. This is currently not supported in symfony/config, meaning that we'd have to update the configuration as well as the schema. Now think about JSON schema and you see why I'm not keen on doing that. I'll reference Generate XSD + JSON schema from Configuration definition symfony/symfony#29560 since I already discussed this with @nicolas-grekas and @stof at previous occasions.
3. Last and most importantly: time. I simply haven't had time to start working on the above. If anyone wants to give this a crack, please let me know and we can chat.

I understand that dropping YAML is a source of frustration for a lot of Symfony folks, but please understand the reasons why we're doing it: with our current team strength, it's not feasible to maintain a mapping driver based on a format that is inherently risky because of its lack of schema. With symfony/config, the component itself can validate the provided data against the "schema" you define via Configuration, hopefully catching many of the issues that we've previously had with invalid mapping files before they cause strange issues in the mapping. Thanks for understanding.

[strongholdmedia]

You could just as much have the annotation stuff removed instead, as it is a blatant violation of SOLID / Single Responsibility Principle.
(My 50 cents on technical correctness.)