-
Notifications
You must be signed in to change notification settings - Fork 4
Data members
The TSDRReq contains a number of members, which are populated after a call to one or more methods (usually the getTSDRInfo method). The most useful of these is the TSDRData object, which contains status information for the trademark application that was the subject of the getTSDRInfo. Other members give access to additional data, such as trademark images, the PTO-supplied zip and XML files, and other data as documented below. Some of these members may not be set if you use methods other than getTSDRInfo (i.e. using only a subset of the getXMLData, getCSVData and getTSDRMap methods), or if the ZIP format is not used (for example, images are provided only in the ZIP files). If invoking the stages individually, see the documentation for those methods in the section Methods for information on which stages set which members.
The TSDRData object is usually the only member that will be referenced. It contains status information in TSDRSingle and TSDRMulti in the form of dictionaries whose keys generally correspond to the XML tags used by the PTO. Full documentation of their contents is in TSDRData contents. It includes the following members:
TSDRMapIsValid is a boolean value that indicates whether the status data in TSDRSigle and TSDRMulti have been set.
TSDRSingle is a dictionary that holds single-valued information regarding the trademark application. This refers to data that has only one value; for example the application number, or the registration date. Each such value is accessed by the key associated with the field. For example, TSDRSingle["ApplicationNumber"] addresses the mark's application number. The keys typically correspond to the attribute names in the XML data provided by TSDR (which may vary from the labels displayed on TSDR itself). The values are strings (even if the value is entirely numeric, such as the application number).
In Plumage-py TSDRSingle is implemented as a Python dict. In Plumage-dotnet (C#), it is implemented as Dictionary<string, string>.
TSDRMulti is used where the data associated with a mark is capable of having multiple values. An example is the events in the trademark's prosecution history. There are usually several possible events associated with a trademark application, from the initial filing, possible office actions and responses, registration, cancellation, etc.
TSDRMulti is a dictionary of lists. A key (e.g. MarkEventList) is used to access a list of items (e.g., a list of events). Each element in the list is itself a dictionary that describes the particular item (e.g. a particular event). The elements are ordered in the same order as presented by the PTO in its XML file.
For example:
-
TSDRMulti["MarkEventList"]is a list of events associated with the application. -
TSDRMulti["MarkEventList"][0]is the entry describing the first event (the most recent, as the PTO currently orders the entries) in that list. -
TSDRMulti["MarkEventList"][0]["MarkEventDescription"]is a description of that event (e.g., immediately after a mark is published for opposition, this text will be "PUBLISHED FOR OPPOSITION").
In Plumage-py, TSDRMulti is represented as a dict. Each entry in the dict is a list. Each entry in the list is a dict whose keys and data are each strings.
In Plumage-dotnet, TSDRMulti is represented as type Dictionary<string, List<Dictionary<string, string>>>. Each entry in the Dictionary is represented as type List<Dictionary<string, string>>; and each entry in the List is of type Dictionary<string, string>.
All keys for recurring data end in the characters "List" (e.g., MarkEventList, ApplicantList, AssignmentList). No keys for non-recurring data TSDRSingle end in "List".
If this explanation sounds a little obtuse, take a look at the Basic examples; in practice it's pretty straightforward.
A complete list of elements returned in TSDRData can be found in TSDRData contents.
The XMLData member is a string containing the XML data retrieved from TSDR (directly or as encapsulated in a ZIP file). It is the initial data obtained from the PTO. You can use this if you wish to operate directly with the PTO-supplied XML data. This allows Plumage to be used as a means of simply obtaining a mark's XML data, even if you don't wish to use the dictionary-based access.
The CSVData member is a string containing the key/value pairs as comma-separated values, derived from XMLData. The string consists of a series of lines, each consisting of a key and its corresponding value. The key is an alphanumeric string, and the value is a string surrounded by double-quotes. The key and value are separated by a comma, with no spaces on the line, other than within the quote marks. Some examples:
RegistrationNumber,"2564831"
ApplicationNumber,"75181334"
MarkVerbalElementText,"MONTY PYTHON'S FLYING CIRCUS"
ApplicationDate,"1996-10-15"
ApplicantName,"Python (Monty) Pictures Ltd."
In the case of recurring fields, a given set of fields is immediately preceded by the key 'BeginRepeatedField' and immediately followed by the key 'EndRepeatedField'. For example, each one of a series of MarkEvents will appear as follows:
BeginRepeatedField,"MarkEvent"
RawMarkEventDate,"2002-02-05-05:00"
MarkEventDate,"2002-02-05"
MarkEventDescription,"PUBLISHED FOR OPPOSITION"
MarkEventEntryNumber,"19"
EndRepeatedField,"MarkEvent"
The format of this data is intended to allow it to be loaded into most programs that accept comma-separated-value data, e.g. the Open Document Foundation's LibreOffice or Microsoft Excel. (Note: there might be some rare cases where the data supplied by the PTO contains some characters that would prevent it from being parsed as valid CSV data; for example, if a double-quote mark is included in a trademark or an applicant's name. I'm not expecting this CSV-export feature to be much used, so haven't tried to bullet-proof it against all data. If this is an area that turns out to actually get use, I'll revisit this.)
The ZipData field is a binary string containing the zip file retrieved from the PTO. If written to a local file (e.g. "foo.zip"), the resulting file can be used like any standard ZIP file.
This field is set only if data was requested from TSDR in ZIP format (the default); otherwise it is set to None (Plumage-py) or null (Plumage-dotnet).
Two members provide image data provided by TSDR. These fields are set only if data was requested from TSDR in ZIP format (the default), and the ZIP data includes the applicable image data; otherwise they are set to None (Plumage-py) or null (Plumage-dotnet).
The ImageThumb member contains binary data for a thumbnail image of the mark, if provided by PTO. This field corresponds to the ZIP file member markThumbnailImage.jpg, a JPEG file.
The ImageFull member contains binary data for a larger image of the mark, if provided by PTO. This field corresponds to the ZIP file member markImage.jpg. Despite the .jpg suffix, this has been found to be a PNG-format file.
Note: Experience shows that sometimes the ZIP files provided by TSDR do not include valid image files. Specifically, sometimes markImage.jpg is missing, and markThumbnailImage.jpg is an empty (zero-length) file. Plumage will faithfully provide the zero-length thumbnail file to the user. Callers should confirm that the image member (either ImageThumb or ImageFull) is both present and non-zero length before using it.
A set of boolean members are provided to indicate whether the corresponding data member contains valid data. The fields XMLDataIsValid, CSVDataIsValid, and TSDRMapIsValid respectively indicate whether the members XMLData, CSVData, and TSDRMap contain usable data.
Two members provide information about any error conditions detected during processing. ErrorCode is a short string containing a code indicating cause of error. It is intended to be interrogated by the invoking program. ErrorInfo is a longer string containing a human-readable description of the error.
ErrorCode and ErrorInfo are more fully discussed in Errors and exceptions.