Show if property is required in metadata

[GoogleCodeExporter]

When getting the metadata from a specific model I would like to know which 
properties are required. 

I attached a patch that does this.

Original issue reported on code.google.com by vinc...@vincentkriek.nl on 25 Sep 2011 at 6:32

Attachments:

• required.patch

[GoogleCodeExporter]

hi,
thanks for the patch.  it's an idea i had thought of before but decided not to 
implement.  the reason is that you need to decide whether the schema is 
describing the model objects themselves or the format for the data in the 
communication layer.  i've decided to go with the latter.  the difference 
between the 2 situations (with regards to this patch) is that while a property 
may be required from the standpoint of the model object, it _may not_ be 
required in the context of a specific request (e.g. a partial update may only 
specify a few fields).  

that said, i can understand the desire to know this sort of info about a model, 
possibly along with things like "verbose_name", "default", and "choices".  
maybe it would make more sense to add some schema annotations with interesting 
metadata.  thoughts?

Original comment by jahlborn@gmail.com on 26 Sep 2011 at 11:18

[GoogleCodeExporter]

The thing what I am trying to do is make automated documentation based on the 
metadata, at least that was the plan at first. I would like to make a few 
request and based on that, make documentation. What I could do instead of that 
is base the documentation of the model.py directly...

I thought it would be nicer if the documentation wasn't connected to the api at 
all (so a completely different (app engine) project. 

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 8:20

[GoogleCodeExporter]

i'm not sure i follow what you are saying.  like i said, a lot of the extra 
information about properties could be included xml schema as schema annotations 
(just to be clear, i'm talking about information in the xml, not in the python 
code).

for example:

<xs:element name="foo" type="xs:string>
  <xs:annotation>
    <rest:metadata required="true" default="blah" verbose_name="Pretty Foo"/>
  </xs:annotation>
</xs:element>

Original comment by jahlborn@gmail.com on 27 Sep 2011 at 12:07

[GoogleCodeExporter]

My question is, why wouldn't you add those? 

And on the required note, I think it is obvious that a required field is not 
required to be updated, just required to be filled. Same with the NOT NULL in 
MySQL for example.

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 12:46

[GoogleCodeExporter]

i think adding that information would be useful, i'm trying to determine if it 
would fit your needs.  

i understand your mysql example, but in this case i still think that the schema 
isn't for describing the internal model, it is for describing how to 
communicate with the api.  for instance, you should be able to use the schema 
to validate your communication with the rest server.  

Original comment by jahlborn@gmail.com on 27 Sep 2011 at 1:25

[GoogleCodeExporter]

than the verbose_name isn't useful as well, just choices would be useful, 
correct? I will go implement this later tonight.

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 1:43

[GoogleCodeExporter]

i think you are confusing what i am saying.  i'm saying that i don't want to 
add the required field to the xml schema definition, because the schema proper 
should describe the transport layer.  however, i'm also saying that the in the 
schema annotations we could put all this "extra" information which might be 
useful for other purposes (aka understanding everything about the underlying 
entity).  in this extra metadata, i think things like "required", "default", 
"choices", "verbose_name", "actual_type" (the property class type name), and 
possibly even the python doc string from the property (the "__doc__" property). 
 a future thing might be model/field level access permissions (like 
access="read" or access="read,write").

Original comment by jahlborn@gmail.com on 27 Sep 2011 at 7:29

[GoogleCodeExporter]

What is this schema annotation that you speak of, does it already exist? 

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 7:30

[GoogleCodeExporter]

Schema annotation should be a subtag of xs:element, am I correct?

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 7:46

[GoogleCodeExporter]

did you see my example above (which is slightly incorrect in retrospect)?  xml 
schema supports "annotation" elements nested under each element.  within this 
element, you can add a "documentation" element with free form text (i was 
thinking you could use this to include the "__doc__" info) as well as an 
"appinfo" element with any other xml which you want to include.  in my example 
above, i was including a new "metadata" element within a custom namespace.  a 
full example could be:

<xs:element name="foo" type="xs:string>
  <xs:annotation>
    <xs:appinfo>
      <rest:metadata required="true" default="blah" verbose_name="Pretty Foo"
                     xmlns:rest="uri:com.boomi.rest">
        <rest:choices>
          <rest:choice>val1</rest:choice>
          <rest:choice>val2</rest:choice>
        </rest:choices>
      </rest:metadata>
    </xs:appinfo>
    <xs:documentation>
      The foo property holds information about the foobar.
    </xs:documentation>
  </xs:annotation>
</xs:element>

(note, the choices could potentially be captured as a custom schema enumeration 
type).

Original comment by jahlborn@gmail.com on 27 Sep 2011 at 7:48

[GoogleCodeExporter]

I will look into this tonight.

I would like to thank you for your help and guidance (maybe overstated but 
still).

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 7:58

[GoogleCodeExporter]

A comment, the documentation should be part of the model element, not property 
because a property can't have a __doc__ string.

This is a first draft, it has the features I need, although i think it is quite 
complete. I will look into this later this week.

Original comment by vinc...@vincentkriek.nl on 27 Sep 2011 at 10:08

Attachments:

• annotation.patch

[GoogleCodeExporter]

This issue was closed by revision r65.

Original comment by jahlborn@gmail.com on 13 Oct 2011 at 1:46

• Changed state: Fixed

[GoogleCodeExporter]

Original comment by jahlborn@gmail.com on 6 Jun 2012 at 1:07

• Added labels: Milestone-Release-1.0.6